Laravel Passport——OAuth2 API 认证系统源码解析（上）

前言

在 Laravel 中，实现基于传统表单的登陆和授权已经非常简单，但是如何满足 API 场景下的授权需求呢？在 API 场景里通常通过令牌来实现用户授权，而非维护请求之间的 Session 状态。在 Laravel 项目中使用 Passport 可以轻而易举地实现 API 授权认证，Passport 可以在几分钟之内为你的应用程序提供完整的 OAuth2 服务端实现。

首先我们可以先了解一下 OAuth2 : 理解OAuth 2.0

可以看出来，OAuth2 的授权模式分为 4 种，相应的 Passport 的授权模式也是 4 中。下面，我们就会逐一进行源码分析。

Passport 服务的注册启动

  1. class PassportServiceProvider extends ServiceProvider
  2. {
  3.     public function register()
  4.     {
  5.         $this->registerAuthorizationServer();
  7.         $this->registerResourceServer();
  9.         $this->registerGuard();
  10.     }
  11. }

我们知道 OAuth2 大致由 客户、客户端、认证服务器、资源服务器 等构成。 在这里，我们扮演着 认证服务器 与 资源服务器 的角色。

认证服务器注册

  1. protected function registerAuthorizationServer()
  2. {
  3.     $this->app->singleton(AuthorizationServer::class, function () {
  4.         return tap($this->makeAuthorizationServer(), function ($server) {
  5.             $server->enableGrantType(
  6.                 $this->makeAuthCodeGrant(), Passport::tokensExpireIn()
  7.             );
  9.             $server->enableGrantType(
  10.                 $this->makeRefreshTokenGrant(), Passport::tokensExpireIn()
  11.             );
  13.             $server->enableGrantType(
  14.                 $this->makePasswordGrant(), Passport::tokensExpireIn()
  15.             );
  17.             $server->enableGrantType(
  18.                 new PersonalAccessGrant, new DateInterval('P1Y')
  19.             );
  21.             $server->enableGrantType(
  22.                 new ClientCredentialsGrant, Passport::tokensExpireIn()
  23.             );
  25.             if (Passport::$implicitGrantEnabled) {
  26.                 $server->enableGrantType(
  27.                     $this->makeImplicitGrant(), Passport::tokensExpireIn()
  28.                 );
  29.             }
  30.         });
  31.     });
  32. }

AuthorizationServer 认证服务器是 League OAuth2 server 的一个类，是 League 关于 OAuth2 的实现类。这个认证服务器类需要 5 个参数，分别代表 客户端、token 令牌、scope 作用范围、加密私钥、加密 key。

  1. class AuthorizationServer implements EmitterAwareInterface
  2. {
  3.     public function __construct(
  4.         ClientRepositoryInterface $clientRepository,
  5.         AccessTokenRepositoryInterface $accessTokenRepository,
  6.         ScopeRepositoryInterface $scopeRepository,
  7.         $privateKey,
  8.         $encryptionKey,
  9.         ResponseTypeInterface $responseType = null
  10.     ) {
  11.         $this->clientRepository = $clientRepository;
  12.         $this->accessTokenRepository = $accessTokenRepository;
  13.         $this->scopeRepository = $scopeRepository;
  15.         if ($privateKey instanceof CryptKey === false) {
  16.             $privateKey = new CryptKey($privateKey);
  17.         }
  18.         $this->privateKey = $privateKey;
  19.         $this->encryptionKey = $encryptionKey;
  20.         $this->responseType = $responseType;
  21.     }
  22. }

这些不同的 Repository 均是各个接口类，这些类规定了各个部分的功能。Passport 实现了上述几个接口类：

  1. public function makeAuthorizationServer()
  2. {
  3.     return new AuthorizationServer(
  4.         $this->app->make(Bridge\ClientRepository::class),
  5.         $this->app->make(Bridge\AccessTokenRepository::class),
  6.         $this->app->make(Bridge\ScopeRepository::class),
  7.         $this->makeCryptKey('oauth-private.key'),
  8.         app('encrypter')->getKey()
  9.     );
  10. }
  12. protected function makeCryptKey($key)
  13. {
  14.     return new CryptKey(
  15.         'file://'.Passport::keyPath($key),
  16.         null,
  17.         false
  18.     );
  19. }

oauth-private.key 这个私钥由 php artisan passport:keys 命令生成。encrypter 的加密 key 是 .env 文件的 key 属性。

构建认证服务器之后，还要对认证服务器注册授权方式。 Passport 的授权方式有传统的 OAuth2 : 授权码模式、密码模式、隐性模式、客户端模式，还有 刷新令牌模式、个人授权模式 等。

  1. protected function makeAuthCodeGrant()
  2. {
  3.     return tap($this->buildAuthCodeGrant(), function ($grant) {
  4.         $grant->setRefreshTokenTTL(Passport::refreshTokensExpireIn());
  5.     });
  6. }
  8. protected function buildAuthCodeGrant()
  9. {
  10.     return new AuthCodeGrant(
  11.         $this->app->make(Bridge\AuthCodeRepository::class),
  12.         $this->app->make(Bridge\RefreshTokenRepository::class),
  13.         new DateInterval('PT10M')
  14.     );
  15. }

资源服务器注册

类似的, ResourceServer 也是 League 的资源服务器类：

  1. protected function registerResourceServer()
  2. {
  3.     $this->app->singleton(ResourceServer::class, function () {
  4.         return new ResourceServer(
  5.             $this->app->make(Bridge\AccessTokenRepository::class),
  6.             $this->makeCryptKey('oauth-public.key')
  7.         );
  8.     });
  9. }

guard 注册

当我们已经构建好 Passport 服务之后，我们只要利用中间件 Auth:api 就可以利用 Passport 验证 api 的合法性。具体的原理是 中间件 Auth 的参数 api 是指定 guard 的名称，例如 web、api,如果调用的是 api 的 guard 那么就会创建相应的 passport 驱动器：

  1. 'guards' => [
  2.     'web' => [
  3.         'driver' => 'session',
  4.         'provider' => 'users',
  5.     ],
  7.     'api' => [
  8.         'driver' => 'passport',
  9.         'provider' => 'users',
  10.     ],
  11. ],

而 passport 的 guard 驱动器就是这个 TokenGuard: 

  1. protected function registerGuard()
  2. {
  3.     Auth::extend('passport', function ($app, $name, array $config) {
  4.         return tap($this->makeGuard($config), function ($guard) {
  5.             $this->app->refresh('request', $guard, 'setRequest');
  6.         });
  7.     });
  8. }
  10. protected function makeGuard(array $config)
  11. {
  12.     return new RequestGuard(function ($request) use ($config) {
  13.         return (new TokenGuard(
  14.             $this->app->make(ResourceServer::class),
  15.             Auth::createUserProvider($config['provider']),
  16.             $this->app->make(TokenRepository::class),
  17.             $this->app->make(ClientRepository::class),
  18.             $this->app->make('encrypter')
  19.         ))->user($request);
  20.     }, $this->app['request']);
  21. }

授权码模式

授权码模式大概分为 5 个步骤：

  • 第三方 向我们的服务器申请创建客户端。
  • 用户打开客户端以后，客户端会跳转到我们的网站授权页面要求用户给予授权。
  • 用户同意给予客户端授权，我们将会返回 授权码。
  • 客户端使用上一步获得的授权，向认证服务器申请令牌。
  • 客户端使用令牌，向资源服务器申请获取资源。

为何授权码模式需要如此设置步骤可以查看：Why is there an “Authorization Code” flow in OAuth2 when “Implicit” flow works so well?、OAuth2疑问解答

创建客户端

在创建客户端这一步骤，第三方需要提供客户端名称与客户端的 redirect ：

  1. const data = {
  2.     name: 'Client Name',
  3.     redirect: 'http://example.com/callback'
  4. };
  6. axios.post('/oauth/clients', data)
  7.     .then(response => {
  8.         console.log(response.data);
  9.     })
  10.     .catch (response => {
  11.         // List errors on response...
  12.     });

我们在创建成功之后，会返回此客户端的 ID 和密钥。这两个东西十分重要，是后面几个步骤必要的参数。

  1. public function forClients()
  2. {
  3.     $this->router->group(['middleware' => ['web', 'auth']], function ($router) {
  4.         $router->get('/clients', [
  5.             'uses' => 'ClientController@forUser',
  6.         ]);
  8.         $router->post('/clients', [
  9.             'uses' => 'ClientController@store',
  10.         ]);
  12.         $router->put('/clients/{client_id}', [
  13.             'uses' => 'ClientController@update',
  14.         ]);
  16.         $router->delete('/clients/{client_id}', [
  17.             'uses' => 'ClientController@destroy',
  18.         ]);
  19.     });
  20. }
  22. public function store(Request $request)
  23. {
  24.     $this->validation->make($request->all(), [
  25.         'name' => 'required|max:255',
  26.         'redirect' => 'required|url',
  27.     ])->validate();
  29.     return $this->clients->create(
  30.         $request->user()->getKey(), $request->name, $request->redirect
  31.     )->makeVisible('secret');
  32. }
  34. public function create($userId, $name, $redirect, $personalAccess = false, $password = false)
  35. {
  36.     $client = (new Client)->forceFill([
  37.         'user_id' => $userId,
  38.         'name' => $name,
  39.         'secret' => str_random(40),
  40.         'redirect' => $redirect,
  41.         'personal_access_client' => $personalAccess,
  42.         'password_client' => $password,
  43.         'revoked' => false,
  44.     ]);
  46.     $client->save();
  48.     return $client;
  49. }

跳转授权页面

客户端创建之后，开发者会使用此客户端的 ID 和密钥来请求授权代码，并从应用程序访问令牌。首先，接入应用的用户向你应用程序的 /oauth/authorize 路由发出重定向请求，

  1. Route::get('/redirect', function () {
  2.     $query = http_build_query([
  3.         'client_id' => 'client-id',
  4.         'redirect_uri' => 'http://example.com/callback',
  5.         'response_type' => 'code',
  6.         'scope' => '',
  7.     ]);
  9.     return redirect('http://your-app.com/oauth/authorize?'.$query);
  10. });

这个链接会访问我们的授权路由，我们的服务器会验证上面的四个参数，考察是否存在这个第三方客户端，如果验证通过，将会渲染出我们的授权页面。

  1. public function forAuthorization()
  2. {
  3.     $this->router->group(['middleware' => ['web', 'auth']], function ($router) {
  4.         $router->get('/authorize', [
  5.             'uses' => 'AuthorizationController@authorize',
  6.         ]);
  8.         $router->post('/authorize', [
  9.             'uses' => 'ApproveAuthorizationController@approve',
  10.         ]);
  12.         $router->delete('/authorize', [
  13.             'uses' => 'DenyAuthorizationController@deny',
  14.         ]);
  15.     });
  16. }
  18. public function authorize(ServerRequestInterface $psrRequest,
  19.                           Request $request,
  20.                           ClientRepository $clients,
  21.                           TokenRepository $tokens)
  22. {
  23.     return $this->withErrorHandling(function () use ($psrRequest, $request, $clients, $tokens) {
  24.         $authRequest = $this->server->validateAuthorizationRequest($psrRequest);
  26.         $scopes = $this->parseScopes($authRequest);
  28.         $token = $tokens->findValidToken(
  29.             $user = $request->user(),
  30.             $client = $clients->find($authRequest->getClient()->getIdentifier())
  31.         );
  33.         if ($token && $token->scopes === collect($scopes)->pluck('id')->all()) {
  34.             return $this->approveRequest($authRequest, $user);
  35.         }
  37.         $request->session()->put('authRequest', $authRequest);
  39.         return $this->response->view('passport::authorize', [
  40.             'client' => $client,
  41.             'user' => $user,
  42.             'scopes' => $scopes,
  43.             'request' => $request,
  44.         ]);
  45.     });
  46. }

这里最关键的就是 validateAuthorizationRequest 这个函数：

  1. public function validateAuthorizationRequest(ServerRequestInterface $request)
  2. {
  3.     foreach ($this->enabledGrantTypes as $grantType) {
  4.         if ($grantType->canRespondToAuthorizationRequest($request)) {
  5.             return $grantType->validateAuthorizationRequest($request);
  6.         }
  7.     }
  9.     throw OAuthServerException::unsupportedGrantType();
  10. }

canRespondToAuthorizationRequest 用于验证授权模式与参数的 response_type 是否符合。如果确认授权模式正确，那么接下来就会继续验证以下几项：

  • 客户端 id
  • redirect 重定向地址
  • scopes 授权范围
  • state 客户端状态

客户端

  1. public function validateAuthorizationRequest(ServerRequestInterface $request)
  2. {
  3.     $clientId = $this->getQueryStringParameter(
  4.         'client_id',
  5.         $request,
  6.         $this->getServerParameter('PHP_AUTH_USER', $request)
  7.     );
  8.     if (is_null($clientId)) {
  9.         throw OAuthServerException::invalidRequest('client_id');
  10.     }
  12.     $client = $this->clientRepository->getClientEntity(
  13.         $clientId,
  14.         $this->getIdentifier(),
  15.         null,
  16.         false
  17.     );
  19.     if ($client instanceof ClientEntityInterface === false) {
  20.         $this->getEmitter()->emit(new RequestEvent(RequestEvent::CLIENT_AUTHENTICATION_FAILED, $request));
  21.         throw OAuthServerException::invalidClient();
  22.     }
  24.     ...
  25. }
  27. public function getIdentifier()
  28. {
  29.     return 'authorization_code';
  30. }

客户端的验证主要是利用请求中的参数 client_id，我们会从表 oauth_clients 的表中按照 client_id 来取出数据库记录：

  1. public function getClientEntity($clientIdentifier, $grantType,
  2.                                     $clientSecret = null, $mustValidateSecret = true)
  3. {
  4.     $record = $this->clients->findActive($clientIdentifier);
  6.     if (! $record || ! $this->handlesGrant($record, $grantType)) {
  7.         return;
  8.     }
  10.     $client = new Client(
  11.         $clientIdentifier, $record->name, $record->redirect
  12.     );
  14.     if ($mustValidateSecret &&
  15.         ! hash_equals($record->secret, (string) $clientSecret)) {
  16.         return;
  17.     }
  19.     return $client;
  20. }
  22. public function findActive($id)
  23. {
  24.     $client = $this->find($id);
  26.     return $client && ! $client->revoked ? $client : null;
  27. }
  29. protected function handlesGrant($record, $grantType)
  30. {
  31.     switch ($grantType) {
  32.         case 'authorization_code':
  33.             return ! $record->firstParty();
  34.         case 'personal_access':
  35.             return $record->personal_access_client;
  36.         case 'password':
  37.             return $record->password_client;
  38.         default:
  39.             return true;
  40.     }
  41. }

在表 oauth_clients 中还有两个字段 personal_access、password，对于授权码模式来说这两个字段都要求为 0。

重定向地址

  1. public function validateAuthorizationRequest(ServerRequestInterface $request)
  2. {
  3.     ...
  5.     $redirectUri = $this->getQueryStringParameter('redirect_uri', $request);
  6.     if ($redirectUri !== null) {
  7.         if (
  8.             is_string($client->getRedirectUri())
  9.             && (strcmp($client->getRedirectUri(), $redirectUri) !== 0)
  10.         ) {
  11.             $this->getEmitter()->emit(new RequestEvent(RequestEvent::CLIENT_AUTHENTICATION_FAILED, $request));
  12.             throw OAuthServerException::invalidClient();
  13.         } elseif (
  14.             is_array($client->getRedirectUri())
  15.             && in_array($redirectUri, $client->getRedirectUri()) === false
  16.         ) {
  17.             $this->getEmitter()->emit(new RequestEvent(RequestEvent::CLIENT_AUTHENTICATION_FAILED, $request));
  18.             throw OAuthServerException::invalidClient();
  19.         }
  20.     } elseif (is_array($client->getRedirectUri()) && count($client->getRedirectUri()) !== 1
  21.         || empty($client->getRedirectUri())
  22.     ) {
  23.         $this->getEmitter()->emit(new RequestEvent(RequestEvent::CLIENT_AUTHENTICATION_FAILED, $request));
  24.         throw OAuthServerException::invalidClient();
  25.     }
  27.     ...
  29. }

这部分验证参数中的 redirect_uri 是否与数据库中的重定向地址是否一致。

授权作用域

授权作用域可以让 API 客户端在请求账户授权时请求特定的权限。例如，如果你正在构建电子商务应用程序，并不是所有接入的 API 应用都需要下订单的功能。你可以让接入的 API 应用只被允许授权访问订单发货状态。换句话说，作用域允许应用程序的用户限制第三方应用程序执行的操作。

你可以在 AuthServiceProvider 的 boot 方法中使用 Passport::tokensCan 方法来定义 API 的作用域。tokensCan 方法接受一个作用域名称、描述的数组作为参数。作用域描述将会在授权确认页中直接展示给用户，你可以将其定义为任何你需要的内容：

  1. Passport::tokensCan([
  2.     'place-orders' => 'Place orders',
  3.     'check-status' => 'Check order status',
  4. ]);
  6. public static function tokensCan(array $scopes)
  7. {
  8.     static::$scopes = $scopes;
  9. }

验证授权作用域的时候，只是在 Passport 中验证是否存在该授权作用域：

  1. public function validateAuthorizationRequest(ServerRequestInterface $request)
  2. {
  3.     ...
  5.     $scopes = $this->validateScopes(
  6.         $this->getQueryStringParameter('scope', $request, $this->defaultScope),
  7.         is_array($client->getRedirectUri())
  8.             ? $client->getRedirectUri()[0]
  9.             : $client->getRedirectUri()
  10.     );
  12.     ...
  13. }
  15. public function validateScopes($scopes, $redirectUri = null)
  16. {
  17.     $scopesList = array_filter(explode(self::SCOPE_DELIMITER_STRING, trim($scopes)), function ($scope) {
  18.         return !empty($scope);
  19.     });
  21.     $validScopes = [];
  23.     foreach ($scopesList as $scopeItem) {
  24.         $scope = $this->scopeRepository->getScopeEntityByIdentifier($scopeItem);
  26.         if ($scope instanceof ScopeEntityInterface === false) {
  27.             throw OAuthServerException::invalidScope($scopeItem, $redirectUri);
  28.         }
  30.         $validScopes[] = $scope;
  31.     }
  33.     return $validScopes;
  34. }
  36. public function getScopeEntityByIdentifier($identifier)
  37. {
  38.     if (Passport::hasScope($identifier)) {
  39.         return new Scope($identifier);
  40.     }
  41. }

state

这个字段用于防止 csrf 攻击的，具体可以查看 ：移花接木：针对OAuth2的CSRF攻击

  1. public function validateAuthorizationRequest(ServerRequestInterface $request)
  2. {
  3.     $stateParameter = $this->getQueryStringParameter('state', $request);
  5.         $authorizationRequest = new AuthorizationRequest();
  6.         $authorizationRequest->setGrantTypeId($this->getIdentifier());
  7.         $authorizationRequest->setClient($client);
  8.         $authorizationRequest->setRedirectUri($redirectUri);
  9.         $authorizationRequest->setState($stateParameter);
  10.         $authorizationRequest->setScopes($scopes);
  11. }

验证结束后，接下来就会验证当前用户是否已经授权过，如果已经授权过，那么就会直接返回授权码，否则就会渲染授权页面：

  1. public function authorize(ServerRequestInterface $psrRequest,
  2.                               Request $request,
  3.                               ClientRepository $clients,
  4.                               TokenRepository $tokens)
  5. {
  6.     return $this->withErrorHandling(function () use ($psrRequest, $request, $clients, $tokens) {
  7.         $authRequest = $this->server->validateAuthorizationRequest($psrRequest);
  9.         $scopes = $this->parseScopes($authRequest);
  11.         $token = $tokens->findValidToken(
  12.             $user = $request->user(),
  13.             $client = $clients->find($authRequest->getClient()->getIdentifier())
  14.         );
  16.         if ($token && $token->scopes === collect($scopes)->pluck('id')->all()) {
  17.             return $this->approveRequest($authRequest, $user);
  18.         }
  20.         $request->session()->put('authRequest', $authRequest);
  22.         return $this->response->view('passport::authorize', [
  23.             'client' => $client,
  24.             'user' => $user,
  25.             'scopes' => $scopes,
  26.             'request' => $request,
  27.         ]);
  28.     });
  29. }

验证用户的是否授权首先是查看授权作用域是否与数据库保持一致。由于授权作用域与 token 相互关联，并非与客户端相互关联，所以 scopes 没有在 oauth_clients 表中，而是在 oauth_access_tokens 这个表中。

  1. protected function parseScopes($authRequest)
  2. {
  3.     return Passport::scopesFor(
  4.         collect($authRequest->getScopes())->map(function ($scope) {
  5.             return $scope->getIdentifier();
  6.         })->all()
  7.     );
  8. }
  10. public static function scopesFor(array $ids)
  11. {
  12.     return collect($ids)->map(function ($id) {
  13.         if (isset(static::$scopes[$id])) {
  14.             return new Scope($id, static::$scopes[$id]);
  15.         }
  17.         return;
  18.     })->filter()->values()->all();
  19. }

可以看到，作用域的 identifier 就是 Scope 的 id。

获取已授权 token

token 的获取主要是利用 client_id 与 user_id 在表 oauth_access_tokens 中查询符合条件的 token。

  1. public function findValidToken($user, $client)
  2. {
  3.     return $client->tokens()
  4.                   ->whereUserId($user->getKey())
  5.                   ->whereRevoked(0)
  6.                   ->where('expires_at', '>', Carbon::now())
  7.                   ->latest('expires_at')
  8.                   ->first();
  9. }
  11. public function tokens()
  12. {
  13.     return $this->hasMany(Token::class, 'client_id');
  14. }

在获取到有效的 token 之后，并且 token 的作用域符合请求参数，就会立即返回，不需要用户的重复授权：

  1. protected function approveRequest($authRequest, $user)
  2. {
  3.     $authRequest->setUser(new User($user->getKey()));
  5.     $authRequest->setAuthorizationApproved(true);
  7.     return $this->convertResponse(
  8.         $this->server->completeAuthorizationRequest($authRequest, new Psr7Response)
  9.     );
  10. }

授权成功

用户点击确认按钮，授权成功之后，服务器就会跳转到客户端预设的 redirecturi，并且携带授权码等一系列参数

  1. $router->post('/authorize', [
  2.     'uses' => 'ApproveAuthorizationController@approve',
  3. ]);
  6. public function approve(Request $request)
  7. {
  8.     return $this->withErrorHandling(function () use ($request) {
  9.         $authRequest = $this->getAuthRequestFromSession($request);
  11.         return $this->convertResponse(
  12.             $this->server->completeAuthorizationRequest($authRequest, new Psr7Response)
  13.         );
  14.     });
  15. }

completeAuthorizationRequest 是授权服务器的重要步骤：

  1. public function completeAuthorizationRequest(AuthorizationRequest $authRequest, ResponseInterface $response)
  2. {
  3.     return $this->enabledGrantTypes[$authRequest->getGrantTypeId()]
  4.         ->completeAuthorizationRequest($authRequest)
  5.         ->generateHttpResponse($response);
  6. }
  9. public function completeAuthorizationRequest(AuthorizationRequest $authorizationRequest)
  10. {
  11.     if ($authorizationRequest->getUser() instanceof UserEntityInterface === false) {
  12.         throw new \LogicException('An instance of UserEntityInterface should be set on the AuthorizationRequest');
  13.     }
  15.     $finalRedirectUri = ($authorizationRequest->getRedirectUri() === null)
  16.         ? is_array($authorizationRequest->getClient()->getRedirectUri())
  17.             ? $authorizationRequest->getClient()->getRedirectUri()[0]
  18.             : $authorizationRequest->getClient()->getRedirectUri()
  19.         : $authorizationRequest->getRedirectUri();
  21.     // The user approved the client, redirect them back with an auth code
  22.     if ($authorizationRequest->isAuthorizationApproved() === true) {
  23.         $authCode = $this->issueAuthCode(
  24.             $this->authCodeTTL,
  25.             $authorizationRequest->getClient(),
  26.             $authorizationRequest->getUser()->getIdentifier(),
  27.             $authorizationRequest->getRedirectUri(),
  28.             $authorizationRequest->getScopes()
  29.         );
  31.         $payload = [
  32.             'client_id'             => $authCode->getClient()->getIdentifier(),
  33.             'redirect_uri'          => $authCode->getRedirectUri(),
  34.             'auth_code_id'          => $authCode->getIdentifier(),
  35.             'scopes'                => $authCode->getScopes(),
  36.             'user_id'               => $authCode->getUserIdentifier(),
  37.             'expire_time'           => (new \DateTime())->add($this->authCodeTTL)->format('U'),
  38.             'code_challenge'        => $authorizationRequest->getCodeChallenge(),
  39.             'code_challenge_method' => $authorizationRequest->getCodeChallengeMethod(),
  40.         ];
  42.         $response = new RedirectResponse();
  43.         $response->setRedirectUri(
  44.             $this->makeRedirectUri(
  45.                 $finalRedirectUri,
  46.                 [
  47.                     'code'  => $this->encrypt(
  48.                         json_encode(
  49.                             $payload
  50.                         )
  51.                     ),
  52.                     'state' => $authorizationRequest->getState(),
  53.                 ]
  54.             )
  55.         );
  57.         return $response;
  58.     }
  60.     // The user denied the client, redirect them back with an error
  61.     throw OAuthServerException::accessDenied(
  62.         'The user denied the request',
  63.         $this->makeRedirectUri(
  64.             $finalRedirectUri,
  65.             [
  66.                 'state' => $authorizationRequest->getState(),
  67.             ]
  68.         )
  69.     );
  70. }

这里最重要的就是 issueAuthCode 生成授权码：

  1. protected function issueAuthCode(
  2.     \DateInterval $authCodeTTL,
  3.     ClientEntityInterface $client,
  4.     $userIdentifier,
  5.     $redirectUri,
  6.     array $scopes = []
  7. ) {
  8.     $maxGenerationAttempts = self::MAX_RANDOM_TOKEN_GENERATION_ATTEMPTS;
  10.     $authCode = $this->authCodeRepository->getNewAuthCode();
  11.     $authCode->setExpiryDateTime((new \DateTime())->add($authCodeTTL));
  12.     $authCode->setClient($client);
  13.     $authCode->setUserIdentifier($userIdentifier);
  14.     $authCode->setRedirectUri($redirectUri);
  16.     foreach ($scopes as $scope) {
  17.         $authCode->addScope($scope);
  18.     }
  20.     while ($maxGenerationAttempts-- > 0) {
  21.         $authCode->setIdentifier($this->generateUniqueIdentifier());
  22.         try {
  23.             $this->authCodeRepository->persistNewAuthCode($authCode);
  25.             return $authCode;
  26.         } catch (UniqueTokenIdentifierConstraintViolationException $e) {
  27.             if ($maxGenerationAttempts === 0) {
  28.                 throw $e;
  29.             }
  30.         }
  31.     }
  32. }

其中 generateUniqueIdentifier 就是生成授权码的步骤，这个授权码也是表 oauth_auth_codes 的 id：

  1. protected function generateUniqueIdentifier($length = 40)
  2. {
  3.     try {
  4.         return bin2hex(random_bytes($length));
  5.         // @codeCoverageIgnoreStart
  6.     } catch (\TypeError $e) {
  7.         throw OAuthServerException::serverError('An unexpected error has occurred');
  8.     } catch (\Error $e) {
  9.         throw OAuthServerException::serverError('An unexpected error has occurred');
  10.     } catch (\Exception $e) {
  11.         // If you get this message, the CSPRNG failed hard.
  12.         throw OAuthServerException::serverError('Could not generate a random string');
  13.     }
  14.     // @codeCoverageIgnoreEnd
  15. }
  17. public function persistNewAuthCode(AuthCodeEntityInterface $authCodeEntity)
  18. {
  19.     $this->database->table('oauth_auth_codes')->insert([
  20.         'id' => $authCodeEntity->getIdentifier(),
  21.         'user_id' => $authCodeEntity->getUserIdentifier(),
  22.         'client_id' => $authCodeEntity->getClient()->getIdentifier(),
  23.         'scopes' => $this->formatScopesForStorage($authCodeEntity->getScopes()),
  24.         'revoked' => false,
  25.         'expires_at' => $authCodeEntity->getExpiryDateTime(),
  26.     ]);
  27. }

授权码转为令牌

由于 client_id 是公开的，因此上一步授权码的获取理论上很容易，真正重要的是授权码转为令牌：

  1. Route::get('/callback', function (Request $request) {
  2.     $http = new GuzzleHttp\Client;
  4.     $response = $http->post('http://your-app.com/oauth/token', [
  5.         'form_params' => [
  6.             'grant_type' => 'authorization_code',
  7.             'client_id' => 'client-id',
  8.             'client_secret' => 'client-secret',
  9.             'redirect_uri' => 'http://example.com/callback',
  10.             'code' => $request->code,
  11.         ],
  12.     ]);
  14.     return json_decode((string) $response->getBody(), true);
  15. });

这一步需要客户端提供注册时返回的密码，

  1. public function forAccessTokens()
  2. {
  3.     $this->router->post('/token', [
  4.         'uses' => 'AccessTokenController@issueToken',
  5.         'middleware' => 'throttle',
  6.     ]);
  7. }
  9. public function issueToken(ServerRequestInterface $request)
  10. {
  11.     return $this->withErrorHandling(function () use ($request) {
  12.         return $this->convertResponse(
  13.             $this->server->respondToAccessTokenRequest($request, new Psr7Response)
  14.         );
  15.     });
  16. }

这一步需要验证的东西非常繁多，我们分部分来看：

客户端验证

客户端验证主要校验 client_id、 client_secret、redirect_uri :

  1. public function respondToAccessTokenRequest(
  2.     ServerRequestInterface $request,
  3.     ResponseTypeInterface $responseType,
  4.     \DateInterval $accessTokenTTL
  5. ) {
  7.     $client = $this->validateClient($request);
  9.     ...
  11. }
  13. protected function validateClient(ServerRequestInterface $request)
  14. {
  15.     list($basicAuthUser, $basicAuthPassword) = $this->getBasicAuthCredentials($request);
  17.     $clientId = $this->getRequestParameter('client_id', $request, $basicAuthUser);
  19.     // If the client is confidential require the client secret
  20.     $clientSecret = $this->getRequestParameter('client_secret', $request, $basicAuthPassword);
  22.     $client = $this->clientRepository->getClientEntity(
  23.         $clientId,
  24.         $this->getIdentifier(),
  25.         $clientSecret,
  26.         true
  27.     );
  29.     $redirectUri = $this->getRequestParameter('redirect_uri', $request, null);
  31.     return $client;
  32. }
  34. protected function getBasicAuthCredentials(ServerRequestInterface $request)
  35. {
  36.     if (!$request->hasHeader('Authorization')) {
  37.         return [null, null];
  38.     }
  40.     $header = $request->getHeader('Authorization')[0];
  41.     if (strpos($header, 'Basic ') !== 0) {
  42.         return [null, null];
  43.     }
  45.     if (!($decoded = base64_decode(substr($header, 6)))) {
  46.         return [null, null];
  47.     }
  49.     if (strpos($decoded, ':') === false) {
  50.         return [null, null]; // HTTP Basic header without colon isn't valid
  51.     }
  53.     return explode(':', $decoded, 2);
  54. }

验证授权码

客户端的密码验证通过后，就会开始验证授权码，授权码的验证主要涉及 expire_time、client_id、auth_code_id:

  1. public function respondToAccessTokenRequest(
  2.     ServerRequestInterface $request,
  3.     ResponseTypeInterface $responseType,
  4.     \DateInterval $accessTokenTTL
  5. ) {
  7.     ...
  9.     $encryptedAuthCode = $this->getRequestParameter('code', $request, null);
  11.     if ($encryptedAuthCode === null) {
  12.         throw OAuthServerException::invalidRequest('code');
  13.     }
  15.     try {
  16.         $authCodePayload = json_decode($this->decrypt($encryptedAuthCode));
  17.         if (time() > $authCodePayload->expire_time) {
  18.             throw OAuthServerException::invalidRequest('code', 'Authorization code has expired');
  19.         }
  21.         if ($this->authCodeRepository->isAuthCodeRevoked($authCodePayload->auth_code_id) === true) {
  22.             throw OAuthServerException::invalidRequest('code', 'Authorization code has been revoked');
  23.         }
  25.         if ($authCodePayload->client_id !== $client->getIdentifier()) {
  26.             throw OAuthServerException::invalidRequest('code', 'Authorization code was not issued to this client');
  27.         }
  29.         // The redirect URI is required in this request
  30.         $redirectUri = $this->getRequestParameter('redirect_uri', $request, null);
  31.         if (empty($authCodePayload->redirect_uri) === false && $redirectUri === null) {
  32.             throw OAuthServerException::invalidRequest('redirect_uri');
  33.         }
  35.         if ($authCodePayload->redirect_uri !== $redirectUri) {
  36.             throw OAuthServerException::invalidRequest('redirect_uri', 'Invalid redirect URI');
  37.         }
  39.     } catch (\LogicException  $e) {
  40.         throw OAuthServerException::invalidRequest('code', 'Cannot decrypt the authorization code');
  41.     }
  42. }
  44. public function isAuthCodeRevoked($codeId)
  45. {
  46.     return $this->database->table('oauth_auth_codes')
  47.                 ->where('id', $codeId)->where('revoked', 1)->exists();
  48. }

发放令牌

令牌的发放主要是 access_token、refresh_token，并且取消相关的授权码：

  1. public function respondToAccessTokenRequest(
  2.     ServerRequestInterface $request,
  3.     ResponseTypeInterface $responseType,
  4.     \DateInterval $accessTokenTTL
  5. ) {
  7.     // Issue and persist access + refresh tokens
  8.     $accessToken = $this->issueAccessToken($accessTokenTTL, $client, $authCodePayload->user_id, $scopes);
  9.     $refreshToken = $this->issueRefreshToken($accessToken);
  11.     // Inject tokens into response type
  12.     $responseType->setAccessToken($accessToken);
  13.     $responseType->setRefreshToken($refreshToken);
  15.     // Revoke used auth code
  16.     $this->authCodeRepository->revokeAuthCode($authCodePayload->auth_code_id);
  18.     return $responseType;
  19. }

首先需要生成 access_token，之后再对表 oauth_access_tokens 持久化 access_token：

  1. protected function issueAccessToken(
  2.     \DateInterval $accessTokenTTL,
  3.     ClientEntityInterface $client,
  4.     $userIdentifier,
  5.     array $scopes = []
  6. ) {
  7.     $maxGenerationAttempts = self::MAX_RANDOM_TOKEN_GENERATION_ATTEMPTS;
  9.     $accessToken = $this->accessTokenRepository->getNewToken($client, $scopes, $userIdentifier);
  10.     $accessToken->setClient($client);
  11.     $accessToken->setUserIdentifier($userIdentifier);
  12.     $accessToken->setExpiryDateTime((new \DateTime())->add($accessTokenTTL));
  14.     foreach ($scopes as $scope) {
  15.         $accessToken->addScope($scope);
  16.     }
  18.     while ($maxGenerationAttempts-- > 0) {
  19.         $accessToken->setIdentifier($this->generateUniqueIdentifier());
  20.         try {
  21.             $this->accessTokenRepository->persistNewAccessToken($accessToken);
  23.             return $accessToken;
  24.         } catch (UniqueTokenIdentifierConstraintViolationException $e) {
  25.             if ($maxGenerationAttempts === 0) {
  26.                 throw $e;
  27.             }
  28.         }
  29.     }
  30. }
  32. public function getNewToken(ClientEntityInterface $clientEntity, array $scopes, $userIdentifier = null)
  33. {
  34.     return new AccessToken($userIdentifier, $scopes);
  35. }
  37. protected function generateUniqueIdentifier($length = 40)
  38. {
  39.     try {
  40.         return bin2hex(random_bytes($length));
  41.         // @codeCoverageIgnoreStart
  42.     } catch (\TypeError $e) {
  43.         throw OAuthServerException::serverError('An unexpected error has occurred');
  44.     } catch (\Error $e) {
  45.         throw OAuthServerException::serverError('An unexpected error has occurred');
  46.     } catch (\Exception $e) {
  47.         // If you get this message, the CSPRNG failed hard.
  48.         throw OAuthServerException::serverError('Could not generate a random string');
  49.     }
  50.     // @codeCoverageIgnoreEnd
  51. }
  53. public function persistNewAccessToken(AccessTokenEntityInterface $accessTokenEntity)
  54. {
  55.     $this->tokenRepository->create([
  56.         'id' => $accessTokenEntity->getIdentifier(),
  57.         'user_id' => $accessTokenEntity->getUserIdentifier(),
  58.         'client_id' => $accessTokenEntity->getClient()->getIdentifier(),
  59.         'scopes' => $this->scopesToArray($accessTokenEntity->getScopes()),
  60.         'revoked' => false,
  61.         'created_at' => new DateTime,
  62.         'updated_at' => new DateTime,
  63.         'expires_at' => $accessTokenEntity->getExpiryDateTime(),
  64.     ]);
  66.     $this->events->dispatch(new AccessTokenCreated(
  67.         $accessTokenEntity->getIdentifier(),
  68.         $accessTokenEntity->getUserIdentifier(),
  69.         $accessTokenEntity->getClient()->getIdentifier()
  70.     ));
  71. }

类似地，还有生成 refresh_token：

  1. protected function issueRefreshToken(AccessTokenEntityInterface $accessToken)
  2. {
  3.     $maxGenerationAttempts = self::MAX_RANDOM_TOKEN_GENERATION_ATTEMPTS;
  5.     $refreshToken = $this->refreshTokenRepository->getNewRefreshToken();
  6.     $refreshToken->setExpiryDateTime((new \DateTime())->add($this->refreshTokenTTL));
  7.     $refreshToken->setAccessToken($accessToken);
  9.     while ($maxGenerationAttempts-- > 0) {
  10.         $refreshToken->setIdentifier($this->generateUniqueIdentifier());
  11.         try {
  12.             $this->refreshTokenRepository->persistNewRefreshToken($refreshToken);
  14.             return $refreshToken;
  15.         } catch (UniqueTokenIdentifierConstraintViolationException $e) {
  16.             if ($maxGenerationAttempts === 0) {
  17.                 throw $e;
  18.             }
  19.         }
  20.     }
  21. }

BearerToken

为了加强安全性，根据 OAuth2 规范，access_token 与 refresh_token 需要利用 Bearer Token 的方式给出，access token 会被转化为 JWT，refresh token 会被加密:

  1. public function generateHttpResponse(ResponseInterface $response)
  2. {
  3.     $expireDateTime = $this->accessToken->getExpiryDateTime()->getTimestamp();
  5.     $jwtAccessToken = $this->accessToken->convertToJWT($this->privateKey);
  7.     $responseParams = [
  8.         'token_type'   => 'Bearer',
  9.         'expires_in'   => $expireDateTime - (new \DateTime())->getTimestamp(),
  10.         'access_token' => (string) $jwtAccessToken,
  11.     ];
  12. I 
  13.     if ($this->refreshToken instanceof RefreshTokenEntityInterface) {
  14.         $refreshToken = $this->encrypt(
  15.             json_encode(
  16.                 [
  17.                     'client_id'        => $this->accessToken->getClient()->getIdentifier(),
  18.                     'refresh_token_id' => $this->refreshToken->getIdentifier(),
  19.                     'access_token_id'  => $this->accessToken->getIdentifier(),
  20.                     'scopes'           => $this->accessToken->getScopes(),
  21.                     'user_id'          => $this->accessToken->getUserIdentifier(),
  22.                     'expire_time'      => $this->refreshToken->getExpiryDateTime()->getTimestamp(),
  23.                 ]
  24.             )
  25.         );
  27.         $responseParams['refresh_token'] = $refreshToken;
  28.     }
  30.     $responseParams = array_merge($this->getExtraParams($this->accessToken), $responseParams);
  32.     $response = $response
  33.         ->withStatus(200)
  34.         ->withHeader('pragma', 'no-cache')
  35.         ->withHeader('cache-control', 'no-store')
  36.         ->withHeader('content-type', 'application/json; charset=UTF-8');
  38.     $response->getBody()->write(json_encode($responseParams));
  40.     return $response;
  41. }

刷新令牌

如果你的应用程序发放了短期的访问令牌，用户将需要通过在发出访问令牌时提供给他们的刷新令牌来刷新其访问令牌。该申请的 url 与申请令牌的链接相同，仅仅 grant_type 不同：

  1. $response = $http->post('http://your-app.com/oauth/token', [
  2.     'form_params' => [
  3.         'grant_type' => 'refresh_token',
  4.         'refresh_token' => 'the-refresh-token',
  5.         'client_id' => 'client-id',
  6.         'client_secret' => 'client-secret',
  7.         'scope' => '',
  8.     ],
  9. ]);
  11. return json_decode((string) $response->getBody(), true);
  1. public function respondToAccessTokenRequest(
  2.     ServerRequestInterface $request,
  3.     ResponseTypeInterface $responseType,
  4.     \DateInterval $accessTokenTTL
  5. ) {
  6.     // Validate request
  7.     $client = $this->validateClient($request);
  8.     $oldRefreshToken = $this->validateOldRefreshToken($request, $client->getIdentifier());
  9.     $scopes = $this->validateScopes($this->getRequestParameter(
  10.         'scope',
  11.         $request,
  12.         implode(self::SCOPE_DELIMITER_STRING, $oldRefreshToken['scopes']))
  13.     );
  15.     // The OAuth spec says that a refreshed access token can have the original scopes or fewer so ensure
  16.     // the request doesn't include any new scopes
  17.     foreach ($scopes as $scope) {
  18.         if (in_array($scope->getIdentifier(), $oldRefreshToken['scopes']) === false) {
  19.             throw OAuthServerException::invalidScope($scope->getIdentifier());
  20.         }
  21.     }
  23.     // Expire old tokens
  24.     $this->accessTokenRepository->revokeAccessToken($oldRefreshToken['access_token_id']);
  25.     $this->refreshTokenRepository->revokeRefreshToken($oldRefreshToken['refresh_token_id']);
  27.     // Issue and persist new tokens
  28.     $accessToken = $this->issueAccessToken($accessTokenTTL, $client, $oldRefreshToken['user_id'], $scopes);
  29.     $refreshToken = $this->issueRefreshToken($accessToken);
  31.     // Inject tokens into response
  32.     $responseType->setAccessToken($accessToken);
  33.     $responseType->setRefreshToken($refreshToken);
  35.     return $responseType;
  36. }