What is the OAuth Authorization Code Flow?

Oauth

About

The authorization code grant type (flow) works with an intermediate credential called a authorization code.

It is a indirect and redirection-based flow that is optimized for confidential clients.

The client asks first for an authorization code that it is then used to obtain an access tokens (an optionally a refresh tokens) to get access to the protected resources. More on the flow ? See authorization code flow details

Pro and cons

Flow

The authorization code is obtained by using an authorization endpoint (authorization server component) as an intermediary between the client and resource owner (end-user).

Instead of requesting authorization directly from the resource owner,

sequenceDiagram participant CL as Client (App) participant RO as End User (Resource owner) participant AS as Authorization Endpoint participant TE as Token Endpoint CL->>AS: (A) Makes a authorization request by redirecting the end-user browser RO->>AS: (B) The end-user authenticates and authorizes the client AS->>CL: (C) Send a authorization code grant CL->>TE: (D) Asks a access token with the authorization code grant TE->>CL: (E) Send a access token (and opt refresh)

The flow includes the following steps

(A) Authorization request

The client (app) initiates the flow by directing the resource owner's user-agent (end user using a browser) to the authorization endpoint.

See authorization endpoint authorization request

The client includes in this request:

(B) Authorization

The authorization endpoint (authorization server component):

  • authenticates the resource owner (via the user-agent)
  • establishes whether the resource owner grants or denies the client's access request.

(C) Redirection after grant

Assuming the resource owner grants access, the authorization endpoint (authorization server component) redirects the user-agent back to the client using the redirection URI.

The redirection URI includes:

Example:

https://example.com/redirection/path?code=xxxxx&state=xxxxx

Real example:

  • from Google Drive to the Local application:
http://localhost:22726/?
state=BVBGzPxmRgi6MNgj9Hmq
&code=4/0AX4XfWhcZSdBvBXanPSGA5VYYjz0
&scope=email%20openid%https://www.googleapis.com/auth/userinfo.email%20https://www.googleapis.com/auth/docs.test%20https://www.googleapis.com/auth/drive%20https://www.googleapis.com/auth/drive.photos.readonly
&authuser=0
&prompt=consent
  • from Intellij:
https://localhost:62345/?
code=xxxx
&scope=openid+offline_access+r_ide_auth
&state=xxx
Security

They are generally given back in the URL query.

It expose then the authorization code to:

  • browser history attacks,
  • redirect headers,
  • web log leaking
  • and so on.

That's why the authorization code is temporary.

Example in javascript where the URL is processed and the authorization code is deleted from the history.

// get the query string portion of the current url.
const queryString = window.location.search;
if (queryString.includes("code=") && queryString.includes("state=")) {

	// Process the query parameters, get the token ...
	process();

	// Update the ui with the new auth state
	updateUI();

	// Remove the querystring parameters from the redirect
	window.history.replaceState({}, document.title, redirectPath);
}

(D) Client request access token

The client requests an access token from the authorization server's token endpoint by including the authorization code received in the previous step.

When making the request, the client authenticates with the token_endpoint (authorization server).

The client (app) includes the redirection URI used to obtain the authorization code for verification.

(E) Getting access token and, optionally, a refresh token

The token endpoint (authorization server component):

If valid, the token endpoint (authorization server component) responds back with an access token and, optionally, a refresh token.

Example of a call to

https://tenant.example.com/oauth/token

could result into

{
   "access_token":"yhEvm8U6uG0gPmoUDuLn3bENGIMceiFz",
   "id_token":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZ.... JWT",
   "scope":"openid profile email",
   "expires_in":86400,
   "token_type":"Bearer"
}

Documentation / Reference





Discover More
How does Single Sign-on (SSO) authentication work?

Single Sign-On (SSO, trusted sign-on) is the ability: to require a user to sign once and gain access to different applications. SSO is also known as: as Trusted sign-on or Multi-Domain Security...
Oauth
In OAuth, what is the state query parameter known as Local State?

The state query parameter is an opaque value used by the client (app) in redirection flow to maintain the state between the and (response) (ie to restore or continue the navigation of the user). ...
Oauth
OAuth - Authorization Code

An authorization code is a intermediate credential used in a authorization code flow to retrieve a access token. It's a shared secret that does not long live because it's passed back via the query parameters...
Oauth
OAuth - Implicit Grant and flow

The implicit grant is a grant type (flow) that issued directly an access token. (It does not support the issuance of refresh tokens). This grant type is called implicit, as no intermediate credentials...
Oauth
OAuth - Resource Owner Password Credentials / Password Credentials Flow

This page is the authentication via the password credentials (ie login+password) in OAuth. This type of authentication is known in Oauth as: the Password Credentials Flow. the Resource owner password...
Oauth
OAuth - Token Endpoint

The token endpoint is an authorization endpoint used by the client to obtain an access token by presenting its: authorization grant or refresh token. The token endpoint is used with every authorization...
Oauth
Oauth - Access Token

An access token is a token representing an access authorization created during: a implicit grant flow or a authorization code flow session identifier It is a string representing an access authorization...
Oauth
Oauth - Authorization Grant (Resource Owner Authorization|Authorization Credentials)

An Authorization Grant is a credential representing the resource owner's authorization to access its protected resources. The flow for each type of grant is expressed using grant type: one of four...
Oauth
Oauth - Credential

This page lists all token used in OAuth Credential Type Type Description Used to access the protected resources Used to get a access token (and eventually a refresh token ...
Oauth
Oauth - Flow (Abstract Protocol Flow)

The abstract OAuth 2.0 flow describes the interaction between the four roles. For each type of grant, you got a flow: Type / Flow Description Client Type (Public / Private) Direction Type Redirection...



Share this page:
Follow us:
Task Runner