README

Symfony SDK for Auth0 身份验证和管理 API。

📚 文档 - 🚀 入门 - 💬 反馈

文档

• 文档站点 — 探索我们的文档站点，了解更多关于 Auth0 的信息。

入门

要求

• PHP 8.1+
• Symfony 6.4 LTS 或 7
  • Symfony 7 的支持是由社区贡献的，目前处于实验性阶段。

请查看我们的 支持策略 以了解语言和框架版本将在未来何时停止支持。

安装

使用 Composer 将依赖项添加到您的应用程序中

composer require auth0/symfony

配置 Auth0

在 Auth0 控制台 中创建一个 常规 Web 应用程序。请确保“令牌端点认证方法”设置为 POST。

接下来，在“设置”页面“应用程序 URI”部分下配置您应用程序的回调和注销 URL

• 允许的回调 URL：认证期间 Auth0 将重定向到的您的应用程序的 URL，例如，http://localhost:8000/callback。
• 允许的注销 URL：注销后 Auth0 将重定向到的您的应用程序的 URL，例如，http://localhost:8000/login。

请注意 域、客户端 ID 和 客户端密钥。这些值将在稍后使用。

配置 SDK

安装后，您应该在您的应用程序中找到一个新文件，config/packages/auth0.yaml。如果此文件不存在，请手动创建它。

以下是一个示例配置，它将使用环境变量来分配值。您应避免在此文件中直接存储敏感凭据，因为它通常会提交到版本控制。

auth0:
  sdk:
    domain: "%env(trim:string:AUTH0_DOMAIN)%"
    client_id: "%env(trim:string:AUTH0_CLIENT_ID)%"
    client_secret: "%env(trim:string:AUTH0_CLIENT_SECRET)%"
    cookie_secret: "%kernel.secret%"

    # custom_domain: "%env(trim:string:AUTH0_CUSTOM_DOMAIN)%"

    # audiences:
    #  - "%env(trim:string:AUTH0_API_AUDIENCE)%"

    # token_cache: cache.auth0_token_cache
    # management_token_cache: cache.auth0_management_token_cache

    scopes:
      - openid
      - profile
      - email
      - offline_access

  authenticator:
    routes:
      callback: "%env(string:AUTH0_ROUTE_CALLBACK)%"
      success: "%env(string:AUTH0_ROUTE_SUCCESS)%"
      failure: "%env(string:AUTH0_ROUTE_FAILURE)%"
      login: "%env(string:AUTH0_ROUTE_LOGIN)%"
      logout: "%env(string:AUTH0_ROUTE_LOGOUT)%"

配置您的 .env 文件

在您的应用程序目录内创建或打开一个 .env.local 文件，并添加以下行

#
# ↓ Refer to your Auth0 application details (https://manage.auth0.com/#/applications) for these values.
#

# Your Auth0 application domain
AUTH0_DOMAIN=...

# Your Auth0 application client ID
AUTH0_CLIENT_ID=...

# Your Auth0 application client secret
AUTH0_CLIENT_SECRET=...

# Optional. Your Auth0 custom domain, if you have one. (https://manage.auth0.com/#/custom_domains)
AUTH0_CUSTOM_DOMAIN=...

# Optional. Your Auth0 API identifier/audience, if used. (https://manage.auth0.com/#/apis)
AUTH0_API_AUDIENCE=...

#
# ↓ These routes will be used by the SDK to direct traffic during authentication.
#

# The route that SDK will redirect to after authentication:
AUTH0_ROUTE_CALLBACK=callback

# The route that will trigger the authentication process:
AUTH0_ROUTE_LOGIN=login

# The route that the SDK will redirect to after a successful authentication:
AUTH0_ROUTE_SUCCESS=private

# The route that the SDK will redirect to after a failed authentication:
AUTH0_ROUTE_FAILURE=public

# The route that the SDK will redirect to after a successful logout:
AUTH0_ROUTE_LOGOUT=public

请确保此 .env.local 文件包含在您的 .gitignore 中。它永远不应该提交到版本控制。

配置您的 security.yaml 文件

打开您的应用程序的 config/packages/security.yaml 文件，并根据以下示例进行更新

security:
  providers:
    auth0_provider:
      id: Auth0\Symfony\Security\UserProvider

  firewalls:
    auth0:
      pattern: ^/private$ # A pattern example for stateful (session-based authentication) route requests
      provider: auth0_provider
      custom_authenticators:
        - auth0.authenticator
    api:
      pattern: ^/api # A pattern example for stateless (token-based authorization) route requests
      stateless: true
      provider: auth0_provider
      custom_authenticators:
        - auth0.authorizer
    dev:
      pattern: ^/(_(profiler|wdt)|css|images|js)/
      security: false
    main:
      lazy: true

  access_control:
    - { path: ^/api$, roles: PUBLIC_ACCESS } # PUBLIC_ACCESS is a special role that allows everyone to access the path.
    - { path: ^/api/scoped$, roles: ROLE_USING_TOKEN } # The ROLE_USING_TOKEN role is added by the Auth0 SDK to any request that includes a valid access token.
    - { path: ^/api/scoped$, roles: ROLE_READ_MESSAGES } # This route will expect the given access token to have the `read:messages` scope in order to access it.

更新您的 config/bundle.php

SDK 包应由 Symfony Flex 项目自动检测并注册，但您可能需要将 Auth0Bundle 添加到您的应用程序的包注册表中。无论如何，注册该包是个好主意，以确保安全。

<?php

return [
    /*
     * Leave any existing entries in this array as they are.
     * You should just append this line to the end:
     */

    Auth0\Symfony\Auth0Bundle::class => ['all' => true],
];

可选：添加身份验证辅助路由

SDK 包含许多预构建的 HTTP 控制器，可用于处理身份验证。这些控制器不是必需的，但在入门时可能很有帮助。在许多情况下，这些可能提供了您将 Auth0 集成到应用程序所需的所有功能，提供了一个即插即用的解决方案。

要使用这些，打开您的应用程序的 config/routes.yaml 文件，并添加以下行

login: # Send the user to Auth0 for authentication.
  path: /login
  controller: Auth0\Symfony\Controllers\AuthenticationController::login

callback: # This user will be returned here from Auth0 after authentication; this is a special route that completes the authentication process. After this, the user will be redirected to the route configured as `AUTH0_ROUTE_SUCCESS` in your .env file.
  path: /callback
  controller: Auth0\Symfony\Controllers\AuthenticationController::callback

logout: # This route will clear the user's session and return them to the route configured as `AUTH0_ROUTE_LOGOUT` in your .env file.
  path: /logout
  controller: Auth0\Symfony\Controllers\AuthenticationController::logout

推荐：配置缓存

SDK在其配置中提供了两个缓存属性：token_cache 和 management_token_cache。这些与任何PSR-6缓存实现兼容，其中Symfony提供了一些开箱即用的实现。

它们分别用于存储用于验证访问令牌签名的JSON Web Key Set (JWKS) 结果和生成的管理API令牌。我们建议配置此功能，通过减少SDK需要发出的网络请求数量来提高您应用程序的性能。如果您经常进行管理API请求，这还将极大地帮助避免达到速率限制条件。

以下是一个示例 config/packages/cache.yaml 文件，该文件将配置SDK使用Redis后端进行缓存

framework:
  cache:
    prefix_seed: auth0_symfony_sample

    app: cache.adapter.redis
    default_redis_provider: redis://localhost

    pools:
      auth0_token_cache: { adapter: cache.adapter.redis }
      auth0_management_token_cache: { adapter: cache.adapter.redis }

请查看Symfony缓存文档以获取特定适配器的配置选项。请注意，SDK目前不支持Symfony的“Cache Contract”适配器类型。

示例：检索用户

以下示例展示了如何在控制器中检索已验证用户。对于此示例，我们将创建一个可从位于 /private 的路由访问的模拟 ExampleController 类。

在您的应用程序的 config/routes.yaml 文件中添加一个路由

private:
  path: /private
  controller: App\Controller\ExampleController::private

现在更新或创建一个 src/Controller/ExampleController.php 类，包括以下代码

<?php

namespace App\Controller;

use Symfony\Component\HttpFoundation\Response;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;

class ExampleController extends AbstractController
{
    public function private(): Response
    {
        return new Response(
            '<html><body><pre>' . print_r($this->getUser(), true) . '</pre> <a href="/logout">Logout</a></body></html>'
        );
    }
}

如果您在浏览器中访问 /private 路由，您应该看到已验证用户的详细信息。如果您尚未验证，您将被重定向到 /login 路由进行登录，然后随后返回到 /private。

支持政策

我们的支持窗口由Symfony发布支持和PHP发布支持计划确定，并在以下任一停止接收安全修复时结束，即Symfony框架或PHP运行时，哪个先到先结束。

已过时的语言或框架版本的弃用不被视为破坏性更改，因为Composer优雅地处理这些场景。旧版应用程序将停止接收我们的更新，但将继续在这些不受支持的SDK版本上运行。

注意： 我们目前不支持Symfony LTS版本，但预计在Symfony的6.x分支进入LTS窗口时将添加对此的支持。

注意： Symfony 7支持是社区贡献的，目前被视为实验性。

反馈

贡献

我们感谢对此次仓库的反馈和贡献！在您开始之前，请参阅以下内容

• Auth0的一般贡献指南
• Auth0的行为准则指南

提出问题

要提供反馈或报告错误，请在我们的问题跟踪器上提出问题。

漏洞报告

请勿在公开的Github问题跟踪器上报告安全漏洞。有关披露安全问题的程序，请参阅负责任的披露计划。

Auth0是一个易于实现、可定制的身份验证和授权平台。
要了解更多信息，请访问为什么选择Auth0？

本项目采用MIT许可证。有关更多信息，请参阅LICENSE文件。