OAuth 2.0 Authorization Code Requests and Responses
Jakob Jenkov |
The authorization code grant consists of 2 requests and 2 responses in total. An authorization request + response, and a token request + response.
Authorization Request
The authorization request is sent to the authorization endpoint to obtain an authorization code. Here are the parameters used in the request:
response_type |
Required. Must be set to code |
client_id |
Required. The client identifier as assigned by the authorization server, when the client was registered. |
redirect_uri |
Optional. The redirect URI registered by the client. |
scope |
Optional. The possible scope of the request. |
state |
Optional (recommended). Any client state that needs to be passed on to the client request URI. |
Authorization Response
The authorization response contains the authorization code needed to obtain an access token. Here are the parameters included in the response:
code |
Required. The authorization code. |
state |
Required, if present in request. The same value as sent by the client in the state parameter, if any. |
Authorization Error Response
If an error occurs during authorization, two situations can occur.
The first is, that the client is not authenticated or recognized. For instance, a wrong redirect URI was sent in the request. In that case the authorization server must not redirect the resource owner to the redirect URI. Instead it should inform the resource owner of the error.
The second situation is that client is authenticated correctly, but that something else failed. In that case the following error response is sent to the client, included in the redirect URI:
error |
Required. Must be one of a set of predefined error codes. See the specification for the codes and their meaning. |
error_description |
Optional. A human-readable UTF-8 encoded text describing the error. Intended for a developer, not an end user. |
error_uri |
Optional. A URI pointing to a human-readable web page with information about the error. |
state |
Required, if present in authorization request. The same value as sent in the state parameter in the request. |
Token Request
Once an authorization code is obtained, the client can use that code to obtain an access token. Here is the access token request parameters:
client_id |
Required. The client application's id. |
client_secret |
Required. The client application's client secret . |
grant_type |
Required. Must be set to authorization_code . |
code |
Required. The authorization code received by the authorization server. |
redirect_uri |
Required, if the request URI was included in the authorization request. Must be identical then. |
Token Response
The response to the access token request is a JSON string containing the access token plus some more information:
{ "access_token" : "...",
"token_type" : "...",
"expires_in" : "...",
"refresh_token" : "...",
}
The access_token property is the access token as assigned by the authorization server.
The token_type property is a type of token assigned by the authorization server.
The expires_in property is a number of seconds after which the access token expires, and
is no longer valid. Expiration of access tokens is optional.
The refresh_token property contains a refresh token in case the access token can expire.
The refresh token is used to obtain a new access token once the one returned in this response
is no longer valid.
| Tweet | |
Jakob Jenkov | |
