Lesson 1: The Authorization Code Flow (theory)
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:
With a code value when we use the Authorization Code flow.
Represents the identifier of the client previously registered in the Authorization Server.
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.
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.
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:
Has to be authorization_code to indicate we're using this flow.
The temporary code issued in a previous step.
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.