Get Tokens: Authorization Code Grant Type
Authorization grant is a client redirect based flow. In this scenario:
-
The user will be redirected to the PingFederate authorization endpoint via the user agent (i.e. web browser). This user agent will be used to authenticate the end user and allow them to grant access to the client.
-
Once the user has been authorized, and intermediate code will be granted by the authorization server and returned to the client application via the user agent.
-
Lastly, the client will swap this code for an OAuth access token.
| Capability | |
|---|---|
Browser-based end user interaction |
Yes |
Can use external IDP for authentication |
Yes |
Requires client authentication |
No* |
Requires client to have knowledge of user credentials |
No |
Refresh token allowed |
Yes |
Access token is in context of end user |
Yes |
| Although the authorization code grant type does not require a client secret value, there are security implications to exchanging a code for an access token without client authentication. |
Sample Client Configuration
For the authorization code grant type example below, the following client information will be used:
| Admin Label | OAuth2 Parameter | Example Value |
|---|---|---|
Client ID |
client_id |
ac_client |
Client Authentication |
client_secret |
2Federate |
Allowed Grant Types |
response_type grant_type |
|
Request authorization from user and retrieve authorization code
To initiate the process, the client application will redirect the user to the authorization endpoint. This redirect will contain the applicable attributes URL encoded and included in the query string component of the URL.
Using the above parameters as an example, the application will redirect the user to the following URL:
https://localhost:9031/as/authorization.oauth2?client_id=ac_client&response_type=code&scope=edit&redirect_uri=sample%3A%2F%2Foauth2%2Fcode%2Fcb
This will initiate an authentication process using the browser (user agent). Once the user successfully completes the authorization request, they will be redirected with an authorization code to the redirect_uri value defined in the authorization request (if included) otherwise the user will be returned to the redirect_uri defined when the client was configured.
| For mobile scenarios, the redirect_uri may be a custom URL scheme that will cause the code to be returned to the native application. |
Using the example above, a successful authorization request will result in the resource owner redirected to the following URL with the authorization code included as a code query string parameter:
sample://oauth2/code/cb?code=XYZ...123
|
The client will then extract the code value from the response and, optionally, verify that the state value matches the value provided in the authorization request
Swap the authorization code for an access token
The final step for the client is to swap the authorization code received in the previous step for an access token that can be used to authorize access to resources. By limiting the exposure of the access token to a direct HTTPS connection between the client application and the authorization endpoint, the risk of exposing this access token to an unauthorized party is reduced.
For this to occur, the client makes a HTTP POST request to the token endpoint on the AS. This request will use the following parameters sent in the body of the request:
| Item | Description |
|---|---|
grant_type |
Required to be "authorization_code" |
code |
The authorization code received in the previous step |
redirect_uri |
If this was included in the authorization request, it MUST also be included |
This request should also authenticate as the pre-configured client using either HTTP BASIC authentication or by including the client_id and client_secret values in the request.
To retrieve the access token in the example, the following request will be made:
POST https://localhost:9031/as/token.oauth2 HTTP/1.1 Content-Type: application/x-www-form-urlencoded Authorization: BasicYWNfY2xpZW50OjJGZWRlcmF0ZQ== grant_type=authorization_code &code=XYZ...123
A successful response to this message will result in a 200 OK HTTP response and the access token (and optional refresh token) returned in a JSON structure in the body of the response.
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"access_token":"zzz...yyy",
"token_type":"Bearer",
"expires_in":14400,
"refresh_token":"123...789"
}
The application can now parse the access token and, if present, the refresh token to use for authorization to resources. If a refresh token was returned, it can be used to refresh access token once it expires.