OAuth2 Authorization Code Flow

Grant Type - Authorization Code Flow, steps 1->7 are explained below.

Grant Type - Authorization Code Flow

The flows below assume you have registered the client (your application) and created a user. Typically registration involves a developer account at the service, answering questions about your application, uploading a logo etc.

The user is the single sign on (SSO) account. This could be Google, Facebook, Active Directory ect.

All the tokens and secrets below are overly simplified.

Flow

  1. The user opens your application at https://your-application.local and is not authenticated.

  2. Your application builds an authorization URL and redirect to the authorization service at https://authorisation-service.local

  • client_id is your application id that is registered with the authorization service
  • redirect_uri is the landing page on your application where the now authenticated user will be redirected to along with the authorization-code
  • scope is used for the resource access
  • state is a random string
1
2
3
4
5
6
7
https://authorisation-service.local/authorise?

response_type=code
&client_id=dd938314e8e1
&redirect_uri=https://your-application.local/authorization-code.html
&scope=foo
&state=18b1abb9830d

  1. The user then provides the authorization service their USERNAME and PASSWORD, it then validates the users credentials.

  2. The username/password are never given back to your application. The user is then redirected back to your application based on redirect_uri with query parameters state and code. You must then verify the state parameter is what you passed above, so 18b1abb9830d=18b1abb9830d to protect against Cross Site Request Forgery (CSRF) attacks.

1
2
3
4
https://your-application.local/authorization-code.html?

state=18b1abb9830d
&code=ca9c004f825b
  1. The authorization code is then programatically sent back to https://authorisation-service.local/token with a POST request to exchange it for an access token. This POST includes your client_secret
  • Its considered best practice to to include the Proof Key for Code Exchange (PKCE) flow here (pronounced “pixy”)
  • You just need to provide a client_secret authorization code.
  • client_secret would have been provided when the client was registered.

“The key difference between the PKCE flow and the standard Authorization Code flow is users aren’t required to provide a client_secret. PKCE reduces security risks for native apps, as embedded secrets aren’t required in source code, which limits exposure to reverse engineering.” - developers.onelogin.com

1
2
3
4
5
6
POST https://authorisation-service.local/token

grant_type=authorization_code
&client_id=dd938314e8e1
&client_secret=20166c44bc7e
&code=ca9c004f825b
  1. The response could look like
1
2
3
4
5
6
7
{
  "token_type": "Bearer",
  "expires_in": 86400,
  "access_token": "eaabf941fbd1",
  "scope": "foo",
  "refresh_token": "2501d78c0345"
}
  1. Resource requests then need to include the token_type and access_token in the authorisation header. Note the American spelling with a z. 
1
'Authorization':'Bearer eaabf941fbd1'

References