What is the OAuth Authorization Code Flow?

(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:

• its client identifier,
• requested scope,
• local state (query parameter and value that comes back with the response),
• and a redirection URI to which the authorization server will send the user-agent back once access is granted (or denied).

(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:

• an authorization code
• and any local state provided during Authorization request.

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

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):

• authenticates the client,
• validates the authorization code,
• and ensures that the redirection URI received matches the URI used to redirect the client in step (C).

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"
}