Authorization Code Grant

Jakub Jirutka edited this page Dec 2, 2015 · 9 revisions

An authorization code is returned to the client through a browser redirect after the resource owner (i.e. user) gives consent to the OAAS. The client subsequently exchanges the authorization code for an access token (and often a refresh token). Resource owner’s credentials are never exposed to the client.

Authorize

This scenario begins by redirecting a user (resource owner) to the OAAS authorization URL with a set of following query parameters. The user is prompted to log-in and then asked to approve an authorization request.

Parameter Description
response_type A value of code must be used.
client_id Indicates the client that is making the request. The client ID is obtained during the client registration.
redirect_uri URL where users will be sent after authorization. The value of this parameter must exactly match one of the values registered on OAAS.
scope (Optional) A space delimited set of scopes the client requests. It might be all scopes registered for the client on OAAS or just a subset of them. If not provided then all registered scopes will be issued.
state (Optional) A string value used by the client to maintain state between the request and callback. The OAAS includes this value when redirecting the user back to the client. It should be used for preventing cross-site request forgery attacks.

An example request:

GET https://oaas.example.org/oauth/authorize?response_type=code&client_id=dummy-client&state=xyz&redirect_uri=https://client.example.org/auth
curl https://oaas.example.org/oauth/authorize?response_type=code&client_id=dummy-client&state=xyz&redirect_uri=https://client.example.org/auth

After that OAAS redirects the user back to the client, to URL specified by the redirect_uri. If the user approves the authorization request, then the response contains an authorization code and state parameter (if included in the request). If the user does not approve the request, the response contains an error message. All responses are returned on the query string, as shown below.

A success response:

HTTP/1.1 302 Found
Location: https://client.example.org/auth?code=SplxlOBeZQQYbYS6WxSbIA&state=xyz

An error response:

HTTP/1.1 302 Found
Location: https://client.example.org/auth?error=access_denied&state=xyz

For full list of possible error codes see RFC 6749, 4.1.2.1.

Obtain an Access Token

After the client receives the authorization code, it may exchange it for an access token and a refresh token. This request is an HTTPS post and includes the following parameters:

Field Description
code The authorization code returned from the initial request.
grant_type A value of authorization_code must be used.
redirect_uri The URI registered with the application.
client_id The client authentication, required only when Authorization header is not used.
client_secret The client authentication, required only when Authorization header is not used.

The actual request might look like:

POST /oauth/token HTTP/1.1
Host: oaas.example.org
Authorization: Basic ZHVtbXktY2xpZW50OnRvcC1zZWNyZXQ=
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=l1kSf2&redirect_uri=https://client.example.org/auth

Note: String ZHVtbXktY2xpZW50OnRvcC1zZWNyZXQ= is dummy-client:top-secret encoded in Base64 (i.e. client_id:client_secret).

curl --data "grant_type=authorization_code&code=l1kSf2&redirect_uri=https://client.example.org/auth" \
     --user dummy-client:top-secret https://oaas.example.org/oauth/token

A successful response to this request contains the following fields:

Field Description
access_token The token that can be used to access resources on a resource provider.
expires_in The remaining lifetime of the access token, in seconds.
refresh_token A token that may be used to obtain a new access token. Refresh tokens are valid until the user revokes access.
scope A space delimited set of scopes the token was issued for.
token_type At this time, this field will always have the value Bearer.

and is similar to the following:

{
    "access_token": "ea173f10-babc-404f-b88d-f0ee8d95ff7c",
    "token_type": "bearer",
    "refresh_token": "aba6d32d-4f17-49e6-afcc-1f042f3e6d3c",
    "expires_in": 3600,
    "scope": "urn:zuul:oauth:sample.read urn:zuul:oauth:sample.write"
} 

Refresh an Access Token

When using grant authorization code, a refresh token is returned with an access token. Once the original access token expires, the corresponding refresh token can be sent to the OAAS to obtain a fresh access token without requiring the user to re-authenticate. This allows short-lived tokens to exist between the client and the resource provider, and long-lived tokens between the client and the OAAS.

To obtain a new access token this way, the client performs an HTTPs POST to https://oaas.example.org/oauth/token. The request must include the following parameters:

Field Description
refresh_token The refresh token returned from the authorization code exchange.
grant_type A value of refresh_token must be used.
client_id The client authentication, required only when Authorization header is not used.
client_secret The client authentication, required only when Authorization header is not used.

The actual request might look like:

POST /oauth/token HTTP/1.1
Host: oaas.example.org
Authorization: Basic ZHVtbXktY2xpZW50OnRvcC1zZWNyZXQ=
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=aba6d32d-4f17-49e6-afcc-1f042f3e6d3c

Note: String ZHVtbXktY2xpZW50OnRvcC1zZWNyZXQ= is dummy-client:top-secret encoded in Base64 (i.e. client_id:client_secret).

curl --data "grant_type=refresh_token&refresh_token=aba6d32d-4f17-49e6-afcc-1f042f3e6d3c" \
     --user dummy-client:top-secret https://oaas.example.org/oauth/token

And something like the following should be returned:

{
    "access_token": "3f801c23-2442-4ffe-aece-9bfc778c1ca2",
    "token_type": "bearer",
    "expires_in": 3600,
    "scope": "urn:zuul:oauth:sample.read urn:zuul:oauth:sample.write"
}
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.