Lesson 1: The Authorization Code Flow (theory)

1. Goal

In this lesson we’re going to analyze a very popular OAuth2 Grant Type Flow, the Authorization Code Flow.


2. Lesson Notes

We'll focus only in understanding how the flow is executed, with no code involved at this point. Therefore, there is no need to checkout anything from our code repository.


2.1. The Authorization Code Flow Steps

In this flow, we use a temporary code (Authorization Code) to obtain an Access Token.

This flow requires a user-agent (e.g. a web browser) to:

  • handle redirections
  • allow the Resource Owner to authenticate and grant access to the Client


Step 1: The Authorization Endpoint

The flow starts with the Client requesting authorization from the user, by directing the user-agent to the Authorization endpoint of the Authorization Server.

The OAuth2 specification indicates that the following parameters can be included in the request:

response_type

With a code value when we use the Authorization Code flow.

client_id

Represents the identifier of the client previously registered in the Authorization Server.

redirect_uri

A URI ponting to an endpoint in the Client application capable of handling the Authorization response.

It is usually required to register a whitelist of valid Redirect URIs.

scope

Indicates which 'permissions' will be granted with the Access Token, for example, read and write access.

The supported values are defined by the Authorization Server.

Multiple values can be specified in the request separatting them with a space.

state

This is used for security purposes, to prevent Cross-Site Request Forgery (CSRF) attacks.

For example, the request to this endpoint might look like this:

Step 2: Authenticating the Resource Owner

The Authorization Server authenticates the Resource Owner and asks to grant or deny the permissions that the Client requested.


Step 3: The Redirection URI

The browser is now sent back to the redirect URI provided in the request. This is a Client endpoint capable of handling the authorization response.

The call includes an Authorization Code as a query parameter. This is a code generated by the Authorization Server, usually short-lived for security reasons and that should be used only once.

Let's see how this URI might look like:

Naturally, the state param has to match the one provided in the Authorization request, and the Client should perform this validation.

If the Resource Owner denied access, then the response includes error information instead of the code parameter:

  • error: the error code (access_denied, invalid_request, unauthorized_client,...)
  • error_description: with additional information to help understand the error that occurred
  • error_uri: pointing to a web page with information about the error

Step 4: The Access Token Endpoint

The app now needs to exchange the Authorization Code for an Access Token. This is done by making a POST request to the Authorization Server Token endpoint with some specific parameters:

grant_type

Has to be authorization_code to indicate we're using this flow.

code

The temporary code issued in a previous step.

redirect_uri

Has to match exactly with the one sent previously.

Additionaly, the Client has to authenticate with the Authorization Server, usually by providing the Client Id and a Client Secret. These can be sent using HTTP Basic Authentication or in the body of the request:

Step 5: The Access Token Response

If the request is valid and authorized, the Authorization Server issues an Access Token. The token and its validity period is retrieved in this response, among other relevant fields:

Step 6: Access the Protected Resource

Now finally the client can request secured resources using the Access Token.

The Authorization Server includes information on how to use the Token.

For instance, if the token_type value of the response is Bearer, then the Token is utilized by simply including it in a request header.


3. Resources

- IETF OAuth 2.0 Authorization Framework Specifications

- Front-End App with Spring Security OAuth – Authorization Code Flow