不管进行何种身份验证,本质上都是经过用户凭证 (credentials) 寻找用户 (user class) 的过程,不管是传统的表单 (username/password) 登陆仍是 API 令牌 (token),凭证一般存储于请求对象 (header, body, query 等) 中,所以从请求对象中提取用户凭证并寻找用户的过程,即称之为认证 (Authentication) 。php
Symfony Security 安全组件由 4 个子组件组合而成,它们之间相互独立,你能够选择性的安装。html
组件 | 描述 |
---|---|
security-core | 提供用户密码加密到认证、受权等基本安全功能。 |
security-guard | 一个抽象的身份验证层,用于建立复杂的身份验证系统。 |
security-http | 将安全组件与 HTTP 协议相互集成,以处理安全方面的请求和响应。 |
security-csrf | 为跨域请求伪造 (CSRF) 提供验证和保护。 |
使用 Symfony Security 须要预先安装,因为 security-bundle
已经集成了全部的安全组件,所以只须要安装它便可:git
$ composer require symfony/security-bundle
要实现 Github
登陆,首先须要在 Settings -> Developer settings -> OAuth Apps -> New OAuth App
建立一个应用,并设置认证回调地址(Authorization callback URL
),建立成功以后会分配你一个 Client ID
和 Client Secret
,将此参数复制到项目 环境变量文件:github
# .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; } }
配置环境变量到服务:json
# ./config/services.yaml services: # ... App\OAuth\Github: $clientId: '%env(GITHUB_CLIENT_ID)%' $clientSecret: '%env(GITHUB_CLIENT_SECRET)%'
建立用户对象 (user class),用户对象必需继承 UserInterface。api
// ./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 拦截器:session
# ./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]