[Symfony Security] 使用 Guard 实现 OAuth 登录

Symfony Security

无论进行何种身份验证,本质上都是通过用户凭证 (credentials) 寻找用户 (user class) 的过程,无论是传统的表单 (username/password) 登录还是 API 令牌 (token),凭证通常存储于请求对象 (header, body, query 等) 中,因此从请求对象中提取用户凭证并寻找用户的过程,即称之为认证 (Authentication) 。

Symfony Security 安全组件由 4 个子组件组合而成,它们之间相互独立,你可以选择性的安装。

组件 描述
security-core 提供用户密码加密到认证、授权等基本安全功能。
security-guard 一个抽象的身份验证层,用于创建复杂的身份验证系统。
security-http 将安全组件与 HTTP 协议相互集成,以处理安全方面的请求和响应。
security-csrf 为跨域请求伪造 (CSRF) 提供验证和保护。

使用 Symfony Security 需要预先安装,由于 security-bundle 已经集成了所有的安全组件,因此只需要安装它即可:

$ composer require symfony/security-bundle

实现 Github 登录

要实现 Github 登录,首先需要在 Settings -> Developer settings -> OAuth Apps -> New OAuth App 创建一个应用,并设置认证回调地址(Authorization callback URL),创建成功之后会分配你一个 Client IDClient Secret,将此参数复制到项目 环境变量文件

# .env.local

GITHUB_CLIENT_ID=YOUR_CLIENT_ID
GITHUB_CLIENT_SECRET=YOUR_CLIENT_SECRET

创建一个类用于集中管理 Github API 访问服务,我们使用 http-client 组件作为 HTTP 客户端:

// ./src/OAuth/Github.php

<?php

namespace App\OAuth;

use Symfony\Contracts\HttpClient\HttpClientInterface;

class Github
{
    const AUTHORIZE_URL = 'https://github.com/login/oauth/authorize';
    const ACCESS_TOKEN_URL = 'https://github.com/login/oauth/access_token';
    const USER_URL = 'https://api.github.com/user';

    private $client;
    private $clientId;
    private $clientSecret;

    public function __construct(HttpClientInterface $client, string $clientId, string $clientSecret)
    {
        $this->client = $client;
        $this->clientId = $clientId;
        $this->clientSecret = $clientSecret;
    }

    public function getAuthorizeUrl(string $redirectUri, string $state = null): string
    {
        $query = [
            'client_id' => $this->clientId,
            'redirect_uri' => $redirectUri,
            'state' => $state,
        ];

        return self::AUTHORIZE_URL.'?'.http_build_query($query);
    }

    public function getAccessToken(string $code): array
    {
        $options = [
            'body' => [
                'client_id' => $this->clientId,
                'client_secret' => $this->clientSecret,
                'code' => $code,
            ],
            'headers' => [
                'Accept' => 'application/json',
            ],
        ];

        $response = $this->client->request('POST', self::ACCESS_TOKEN_URL, $options);

        $data = $response->toArray();
        if (isset($data['error'])) {
            throw new \RuntimeException(sprintf('%s (%s)', $data['error_description'], $data['error']));
        }

        return $data;
    }

    public function getUser(string $accessToken): array
    {
        $options = [
            'headers' => [
                'Authorization' => sprintf('token %s', $accessToken),
            ],
        ];

        $response = $this->client->request('GET', self::USER_URL, $options);

        $data = $response->toArray();
        if (isset($data['error'])) {
            throw new \RuntimeException(sprintf('%s (%s)', $data['error_description'], $data['error']));
        }

        return $data;
    }
}

配置环境变量到服务:

# ./config/services.yaml

services:
    # ...
    App\OAuth\Github:
        $clientId: '%env(GITHUB_CLIENT_ID)%'
        $clientSecret: '%env(GITHUB_CLIENT_SECRET)%'

创建用户对象 (user class),用户对象必需继承 UserInterface

// ./src/Entity/User.php

class User implements UserInterface
{
    // ...

    /**
     * @ORM\Column(type="string", length=255, unique=true)
     */
    private $username;

    /**
     * @ORM\Column(type="string", length=255)
     */
    private $nickname;

    /**
     * @ORM\Column(type="string", length=255)
     */
    private $avatar;

    /**
     * @ORM\Column(type="datetime", nullable=true)
     */
    private $updatedAt;

    /**
     * @ORM\Column(type="datetime_immutable")
     */
    private $createdAt;

    // ...
}

创建控制器,跳转到 Github 进行认证:

// ./src/Controller/SecurityController.php

class SecurityController extends AbstractController
{
    /**
     * @Route("/login/oauth/github", name="login_oauth_github")
     *
     * @param Request $request
     * @param Github  $client
     *
     * @return Response
     */
    public function loginWithGithub(Request $request, Github $client)
    {
        // 随机 state 字符串,用于防止 CSRF 攻击
        $state = bin2hex(random_bytes(8));

        $session = $request->getSession();
        $session->set(GithubAuthenticator::STATE, $state);

        // 生成回调地址,该地址即为 Authorization callback URL,需在 Github 上填写
        $callback = $this->generateUrl('login_oauth_github_callback', [], 0);
        $redirect = $client->getAuthorizeUrl($callback, $state);

        return $this->redirect($redirect);
    }

    /**
     * @Route("/login/oauth/github/callback", name="login_oauth_github_callback")
     *
     * 只需要定义路由,这个路由什么都不用干,因为它将会被 Guard 拦截
     */
    public function loginWithGithubCallback()
    {
        // nothing todo...
    }
}

创建 Guard 拦截器实现认证过程:

// ./src/Security/GithubAuthenticator.php

class GithubAuthenticator extends AbstractGuardAuthenticator
{
    use TargetPathTrait;

    const STATE = '_github_oauth_state';

    private $entityManager;
    private $httpUtils;
    private $github;

    public function __construct(EntityManagerInterface $entityManager, HttpUtils $httpUtils, Github $github)
    {
        $this->entityManager = $entityManager;
        $this->httpUtils = $httpUtils;
        $this->github = $github;
    }

    /**
     * 每一个请求都会进入该方法,需要在此过滤那些不相干的请求,返回 false 即可跳过
     */
    public function supports(Request $request)
    {
        // 过滤请求,只拦截回调地址即可,回调地址中 Github 回带上 code
        return $this->httpUtils->checkRequestPath($request, 'login_oauth_github_callback')
            && $request->query->has('code');
    }

    /**
     * 如果匹配到 supports 则调用该方法,用于从请求中获取凭证,用于 getUser
     */
    public function getCredentials(Request $request)
    {
        // 验证 state,防止 CSRF 攻击
        $state = $request->query->get('state');
        if ($state !== $request->getSession()->get(self::STATE)) {
            throw new CustomUserMessageAuthenticationException('Bad authentication state.');
        }

        return $request->query->get('code');
    }

    /**
     * 从 getCredentials 获取到的凭证查找并返回用户,如果返回 NULL 或抛出异常则认证失败
     * 如果返回了用户 (UserInterface),则进入到 checkCredentials
     */
    public function getUser($credentials, UserProviderInterface $userProvider)
    {
        // $credentials 即是 getCredentials 返回的数据
        $token = $this->github->getAccessToken($credentials);

        try {
            $user = $this->github->getUser($token['access_token']);
        } catch (\Throwable $th) {
            // ...
        }

        try {
            // 如果找到用户直接返回,进入下一步
            $entity = $userProvider->loadUserByUsername($user['login']);
        } catch (UsernameNotFoundException $e) {
            // 如果第一次登录,则需要存进数据库
            $entity = new User();
            $entity->setUsername($user['login']);
            $entity->setNickname($user['name']);
            $entity->setAvatar($user['avatar_url']);
            $entity->setCreatedAt(new \DateTimeImmutable());

            $this->entityManager->persist($entity);
            $this->entityManager->flush();
        }

        return $entity;
    }

    /**
     * OAuth 认证不需要检查凭证正确与否
     */
    public function checkCredentials($credentials, UserInterface $user)
    {
        return true;
    }

    /**
     * 任何一步认证失败将调用该方法
     */
    public function onAuthenticationFailure(Request $request, AuthenticationException $exception)
    {
        throw new \RuntimeException($exception->getMessage());
    }

    /**
     * 认证成功后将调用该方法,用于跳转至前一页面
     */
    public function onAuthenticationSuccess(Request $request, TokenInterface $token, $providerKey)
    {
        // getTargetPath 返回用户在认证前停留的页面地址,由 TargetPathTrait 提供
        $targetPath = $this->getTargetPath($request->getSession(), $providerKey);

        if (!$targetPath) {
            $targetPath = $this->httpUtils->generateUri($request, 'app_index');
        }

        return $this->httpUtils->createRedirectResponse($request, $targetPath);
    }

    /**
     * 如果在 secruity.yaml 中配置了access_control 段,当用户权限不足时进入到该方法,否则不执行
     */
    public function start(Request $request, AuthenticationException $authException = null)
    {
        return $this->httpUtils->createRedirectResponse($request, 'app_login');
    }

    /**
     * 是否启用 “自动登录” 功能,OAuth 认证不支持该功能
     */
    public function supportsRememberMe()
    {
        return false;
    }
}

配置 Guard 拦截器:

# ./config/packages/security.yarml

security:
    # ...

    # 定义用户加载器
    providers:
        entity_provider:
            entity: { class: App\Entity\User, property: username }

    # 定义防火墙规则
    firewalls:
        # ...

        # 防火墙区域,可随意定义名称
        my_area:
            # 加载器使用 entity_provider
            provider: entity_provider
            # 拦截器使用 GithubAuthenticator
            guard:
                authenticators:
                    - App\Security\GithubAuthenticator

现在,只需要在登录的地方放上链接至路由 login_oauth_github 即可使用 Github 登录:

<a href="{{ path('login_oauth_github') }}">Github 登录</a>

配置参数参考

以下是常见的安全配置参数说明。

# config/packages/security.yaml

security:
    # 用户密码加密方式,该参数决定了用户密码将由何种方式加密
    encoders:
        # 由系统决定合适的加密方式
        App\Entity\FooUser: auto
        # 由 sodium 方式加密,可取范围:plaintext, pbkdf2, bcrypt, argon2i, native, sodium
        App\Entity\BarUser: sodium

    # 用户加载器,该参数决定用户从何处加载
    providers:
        # 硬编码用户加载器
        my_memory_provider:
            memory:
                users:
                    # 一个称为 foo 的用户,并拥有 ROLE_READER 角色
                    foo: { password: foo_password, roles: ROLE_READER }
                    # 又一个称为 bar 的用户,并拥有 ROLE_EDITOR 角色
                    bar: { password: bar_password, roles: ROLE_EDITOR }
        # 实体用户加载器(从数据库中加载)
        my_entity_provider:
            entity: { class: App\Entity\AcmeUser, property: username }
        # 自定义用户加载器,必需实现 UserProviderInterface 接口
        my_custom_provider:
            id: App\Security\MyCustomProvider

    # 访问区域,可配置多个访问区域,多个区域有先后之分比如 /api 和 /api/user 将先匹配到 /api
    firewalls:
        # 由 /api 开始的请求将匹配到 zone_a 区域,该区域由 my_entity_provider 提供用户
        zone_a:
            pattern: ^/api
            provider: my_entity_provider
        # 由 /admin 开始,并且 host 为 admin.com 的请求将匹配到 area_b 区域,该域由用 my_custom_provider 提供用户
        zone_b:
            pattern: ^/admin
            host: admin.com
            provider: my_custom_provider

    # 访问控制,可配置多个访问区域,多个区域有先后之分
    access_control:
        # 由 /api 开始的请求必需包含 ROLE_API 或 ROLE_USER 角色
        - { path: ^/api, roles: [ROLE_API, ROLE_USER] }
        # 由 /admin 开始的请求必需包含 ROLE_ADMIN 角色
        - { path: ^/admin, roles: ROLE_ADMIN }

    # 用户角色等级
    role_hierarchy:
        # 拥有 ROLE_API 角色的用户将同时具备 ROLE_READER 和 ROLE_EDITOR 权限
        ROLE_API: [ROLE_READER, ROLE_EDITOR]
        # 拥有 ROLE_ADMIN 角色的用户将同时具备 ROLE_ADMIN_ARTICLE, ROLE_ADMIN_COMMENT 权限
        ROLE_ADMIN: [ROLE_ADMIN_ARTICLE, ROLE_ADMIN_COMMENT]
        
阅读 753

推荐阅读