Authorization Code

The Authorization Code grant type uses the authorization server as an intermediary between the client and the resource owner. First, the client directs the resource owner to the authorization server (using a user-agent such as a browser). The authorization server then processes the request and prompts the resource owner for credentials (if not already authenticated), and the authorization server directs the resource owner back to the client with an authorization code through a pre-registered URL. The client then sends its own credentials and the authorization code to the authorization server, in order to get an access token.

The Authorization Code grant type is intended to be used in situations where the client can maintain the confidentiality of its client credentials. For example, the Authorization Code grant type should be used in relation to applications stored on secured servers.

The Authorization Code grant type flow is as follows:

 

The steps are as follows:

  • A) The client redirects the user-agent (usually a browser) to the login page of the authorization server.
  • B) The authorization server presents the login page to the resource owner via the user-agent (if the resource owner is not already authenticated to the authorization server).
  • C/D) The resource owner supplies credentials to the login page. This establishes the identity of the resource owner (authentication).
  • E) The authorization server requests access to resource-owner data on behalf of the client
  • F/G) The resource owner grants the client authorization to access resource owner data.
  • H/I) The authorization server redirects the user-agent to the callback URL supplied by the client in the call (which must match the redirect_uri supplied when the client registered with the authorization server). Once the user-agent has been redirected, the user will see the authorization code, which will be in the form of a URL parameter.
  • J) The client uses the authorization code, along with its client credentials, to request an access token (with an optional refresh token) from the authorization server.
  • K) The authorization server returns an access token to the client, along with the optional refresh token. The authorization token can now be used to request access to protected resources from the resource server.
EXAMPLE FLOW USING WSO2 AND CURL

This example uses command-line curl to emulate the interaction outlined above. This example assumes the client has been registered in API Manager, has provided a redirect_uri, and has been issued a client_id and a client_secret. It also assumes the redirect_uri is invalid (the browser will get a 404 when attempting to redirect to the redirect_uri).

The -k command line option instructs curl to ignore certificates. The -v option specifies verbose mode so we can see the response headers.

Be sure to enclose the URLs in quotation marks. Some characters within the URL are special characters in some operating systems.

A) Client redirects the user-agent to a URL on the WSO2 identity server (via the API Manager):

Open a browser and enter the following URL (below), replacing <client_id> and <redirect_uri> with your own client_id and redirect_uri. This will simulate the redirect the client would normally send the browser.

https://api.byu.edu/authorize?response_type=code&client_id=<client_id>&redirect_uri=<redirect_uri>&scope=openid&state=myteststate

B,C,D,E,F,G) If you (the resource owner) do not currently have a valid CAS session, the user-agent presents the CAS sign-in page. Once you are signed in, you will receive a trust message. Select "Allow".

H) The identity server redirects the user-agent to the client, now with the authorization code. The url fragment looks something like this: redirect_uri?code=authorization code&state=myteststate

I,J) The client uses the authorization code to request an access_token:

curl -v -k -u "client_id:client_secret" -d "grant_type=authorization_code&code=authorization code&redirect_uri=redirect_uri" "https://api.byu.edu/token"
Hostname was NOT found in DNS cache
Trying 128.187.16.246...
Connected to api.byu.edu (128.187.16.246) port 443 (#0)
TLS 1.2 connection using TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
Server certificate: *.byu.edu
Server certificate: DigiCert SHA2 High Assurance Server CA
Server certificate: DigiCert High Assurance EV Root CA
Server auth using Basic with user 'client_id'
POST /token HTTP/1.1
Authorization: Basic base64 encoded client credentials
User-Agent: curl/7.37.1
Host:api.byu.edu
Accept: */*
Content-Length: 103
Content-Type: application/x-www-form-urlencoded

upload completely sent off: 103 out of 103 bytes
HTTP/1.1 200 OK
Date: Wed, 20 May 2015 16:47:20 GMT
Server WSO2-PassThrough-HTTP is not blacklisted
Server: WSO2-PassThrough-HTTP
Content-Type: application/json
Pragma: no-cache
Cache-Control: no-store
Set-Cookie: AUTH_BAL_ID=.w2; path=/
Transfer-Encoding: chunked

Connection #0 to host api.byu.edu left intact
{"scope":"default","token_type":"bearer","expires_in":2998,"refresh_token":"refresh_token","access_token":"access_token"}

K) The JSON returned contains an access_token that can be used for authenticated access to protected resources:

curl -v -k -H "Authorization: Bearer <access_token>" "https://api.byu.edu/byuapi/personsummary/v1/bdm4"