Authorization Code Request

The authorization code grant is used when an application exchanges an authorization code for an access token. After the user returns to the application via the redirect URL, the application will get the authorization code from the URL and use it to request an access token. This request will be made to the token endpoint.

Request Parameters

The access token request will contain the following parameters.

grant_type (required)

The grant_type parameter must be set to “authorization_code”.

code (required)

This parameter is the authorization code that the client previously received from the authorization server.

redirect_uri (possibly required)

If the redirect URI was included in the initial authorization request, the service must require it in the token request as well. The redirect URI in the token request must be an exact match of the redirect URI that was used when generating the authorization code. The service must reject the request otherwise.

client_id (required if no other client authentication is present)

If the client is authenticating via HTTP Basic Auth or some other method, then this parameter is not required. Otherwise, this parameter is required.

If the client was issued a client secret, then the server must authenticate the client. One way to authenticate the client is to accept another parameter in this request, client_secret. Alternately the authorization server can use HTTP Basic Auth. Technically the spec allows the authorization server to support any form of client authentication, and even mentions public/private key pair as an option. However in practice, most servers support the simpler methods of authenticating clients using either or both of the methods mentioned here.

Verifying the authorization code grant

After checking for all required parameters, and authenticating the client if the client was issued a secret, the authorization server can continue verifying the other parts of the request.

The server then checks if the authorization code is valid, and has not expired. The service must then verify that the authorization code provided in the request was issued to the client identified. Lastly, the service must ensure the redirect URI parameter present matches the redirect URI that was used to request the authorization code.

If everything checks out, the service can generate an access token and respond.

Example

The following example shows an authorization grant request for a confidential client.

POST /oauth/token HTTP/1.1Host: authorization-server.com grant_type=authorization_code&code=xxxxxxxxxxx&redirect_uri=https://example-app.com/redirect&client_id=xxxxxxxxxx&client_secret=xxxxxxxxxx

Security Considerations

Preventing replay attacks

If an authorization code is used more than once, the authorization server must deny the subsequent requests. This is easy to accomplish if the authorization codes are stored in a database, since they can simply be marked as used.

If you are implementing self-encoded authorization codes, as in our example code, you’ll need to keep track of the tokens that have been used for the lifetime of the token. One way to accomplish this by caching the code in a cache for the lifetime of the code. This way when verifying codes, we can first check if they have already been used by checking the cache for the code. Once the code reaches its expiration date, it will no longer be in the cache, but we can reject it based on the expiration date anyway.

If a code is used more than once, it should be treated as an attack. If possible, the service should revoke the previous access tokens that were issued from this authorization code.