6.6 KiB
Executable File
layout | title | permalink |
---|---|---|
default | Authorization code grant | /authorization-server/auth-code-grant/ |
Authorization code grant
The authorization code grant should be very familiar if you've ever signed into a web app using your Facebook or Google account.
Flow
Part One
The client will redirect the user to the authorization server with the following parameters in the query string:
response_type
with the valuecode
client_id
with the client identifierredirect_uri
with the client redirect URI. This parameter is optional, but if not send the user will be redirected to a pre-registered redirect URI.scope
a space delimited list of scopesstate
with a CSRF token. This parameter is optional but highly recommended. You should store the value of the CSRF token in the user's session to be validated when they return.
All of these parameters will be validated by the authorization server.
The user will then be asked to login to the authorization server and approve the client.
If the user approves the client they will be redirected from the authorization server to the client's redirect URI with the following parameters in the query string:
code
with the authorization codestate
with the state parameter sent in the original request. You should compare this value with the value stored in the user's session to ensure the authorization code obtained is in response to requests made by this client rather than another client application.
Part Two
The client will now send a POST request to the authorization server with the following parameters:
grant_type
with the value ofauthorization_code
client_id
with the client identifierclient_secret
with the client secretredirect_uri
with the same redirect URI the user was redirect back tocode
with the authorization code from the query string
Note that you need to decode the code
query string first. You can do that with urldecode($code)
.
The authorization server will respond with a JSON object containing the following properties:
token_type
with the valueBearer
expires_in
with an integer representing the TTL of the access tokenaccess_token
a JWT signed with the authorization server's private keyrefresh_token
an encrypted payload that can be used to refresh the access token when it expires.
Setup
Wherever you initialize your objects, initialize a new instance of the authorization server and bind the storage interfaces and authorization code grant:
{% highlight php %} // Init our repositories $clientRepository = new ClientRepository(); // instance of ClientRepositoryInterface $scopeRepository = new ScopeRepository(); // instance of ScopeRepositoryInterface $accessTokenRepository = new AccessTokenRepository(); // instance of AccessTokenRepositoryInterface $authCodeRepository = new AuthCodeRepository(); // instance of AuthCodeRepositoryInterface $refreshTokenRepository = new RefreshTokenRepository(); // instance of RefreshTokenRepositoryInterface
$privateKey = 'file://path/to/private.key'; //$privateKey = new CryptKey('file://path/to/private.key', 'passphrase'); // if private key has a pass phrase $publicKey = 'file://path/to/public.key';
// Setup the authorization server $server = new \League\OAuth2\Server\AuthorizationServer( $clientRepository, $accessTokenRepository, $scopeRepository, $privateKey, $publicKey );
$grant = new \League\OAuth2\Server\Grant\AuthCodeGrant( $authCodeRepository, $refreshTokenRepository, new \DateInterval('PT10M') // authorization codes will expire after 10 minutes );
$grant->setRefreshTokenTTL(new \DateInterval('P1M')); // refresh tokens will expire after 1 month
// Enable the authentication code grant on the server $server->enableGrantType( $grant, new \DateInterval('PT1H') // access tokens will expire after 1 hour ); {% endhighlight %}
Implementation
Please note: These examples here demonstrate usage with the Slim Framework; Slim is not a requirement to use this library, you just need something that generates PSR7-compatible HTTP requests and responses.
The client will redirect the user to an authorization endpoint.
{% highlight php %} $app->get('/authorize', function (ServerRequestInterface $request, ResponseInterface $response) use ($server) {
try {
// Validate the HTTP request and return an AuthorizationRequest object.
$authRequest = $server->validateAuthorizationRequest($request);
// The auth request object can be serialized and saved into a user's session.
// You will probably want to redirect the user at this point to a login endpoint.
// Once the user has logged in set the user on the AuthorizationRequest
$authRequest->setUser(new UserEntity()); // an instance of UserEntityInterface
// At this point you should redirect the user to an authorization page.
// This form will ask the user to approve the client and the scopes requested.
// Once the user has approved or denied the client update the status
// (true = approved, false = denied)
$authRequest->setAuthorizationApproved(true);
// Return the HTTP redirect response
return $server->completeAuthorizationRequest($authRequest, $response);
} catch (OAuthServerException $exception) {
// All instances of OAuthServerException can be formatted into a HTTP response
return $exception->generateHttpResponse($response);
} catch (\Exception $exception) {
// Unknown exception
$body = new Stream('php://temp', 'r+');
$body->write($exception->getMessage());
return $response->withStatus(500)->withBody($body);
}
}); {% endhighlight %}
The client will request an access token using an authorization code so create an /access_token
endpoint.
{% highlight php %} $app->post('/access_token', function (ServerRequestInterface $request, ResponseInterface $response) use ($server) {
try {
// Try to respond to the request
return $server->respondToAccessTokenRequest($request, $response);
} catch (\League\OAuth2\Server\Exception\OAuthServerException $exception) {
// All instances of OAuthServerException can be formatted into a HTTP response
return $exception->generateHttpResponse($response);
} catch (\Exception $exception) {
// Unknown exception
$body = new Stream('php://temp', 'r+');
$body->write($exception->getMessage());
return $response->withStatus(500)->withBody($body);
}
}); {% endhighlight %}