OAuth Code Flow
On this page
OAuth Authorization Code Flow Explained
The OAuth 2.0 authorization code grant type (also called "authorization code flow" or "auth code flow") or auth code flow is the most advanced flow in OAuth. It is also the most flexible OAuth flow, that allows both mobile and web clients to obtain tokens securely and gain access to web APIs. It requires exchanging an authorization code for a token. The following tokens can be requested by the client: access tokens, ID tokens and refresh tokens.
When to Use the OAuth Code Flow
This flow is split into two parts:
*The authorization flow that runs in the browser where the client redirects the user to the OAuth server and the OAuth server redirects the user back to the client when done. *The token flow which is a back-channel call from the client to the token endpoint of the OAuth server in which the client exchanges an authorization code for an access token. In some cases, clients also obtain a refresh token in this response. In an OpenID Connect version of this flow, the client also receives an ID token.
You should use this flow whenever you need to involve the user. This means that whenever you have a client application (a website, a single-page application, or a mobile app) that is operated by a user and needs access to a concrete user's resources. It is a good practice to always use the authorization code flow together with Proof Key for Code Exchange (PKCE), to strengthen the flow's security. PKCE will be required by the OAuth 2.1 specification.
OAuth Code Flow Example
Authorization Endpoint
- Browser redirects to the authorization endpoint at the Token Service of the Authorization Server.
- If the user is not yet authenticated, the Token Service redirects to the Authentication Service. Note that these two entities, while running in the same product, are separate conceptually.
- The User authenticates, and is redirected back to the Token Service.
- The Authorization Server issues a one time token called the authorization code.
Token Endpoint
- The client backend makes a POST request to the token endpoint with the authorization code and client credentials.
- The Authorization Server validates the code and the credentials. It returns an access token and optionally a refresh token if configured.
How the Authorization Code Flow Works
User Authentication
The user is authenticated during the authorization part of the flow. This may involve multiple factors and is not defined by the OAuth specification. In the Curity Identity Server all user authentication is configured in the Authentication Service and is configured per client.
Client Authentication
The client authenticates as part of the token request. There are many ways for a client to authenticate, the most common being client secret. The Curity Identity Server supports the following authentication mechanisms for clients:
- No authentication (public client)
- Secret in POST body
- Secret using Basic Authentication
- Client Assertion JWT
- Mutual TLS (mTLS) client certificate
- Asymmetric Key
- Symmetric Key
- Credential Manager
- JWKS URI
The Authorization Code
Once the authorization flow is done, the redirect back to the client contains an authorization code. This is a nonce, not-more-than-once token, that is to be used a single time. It has a short lifespan (usually less than 30 seconds) and must be presented in the token part of the flow.
The Access Token
The access token is returned by the token endpoint. It is the token that clients can use to call the API and gain access. It is often a Bearer token, and as such must not be sent to untrusted parties. The access token usually has a lifetime of 5-30 minutes.
The Refresh Token
The Refresh Token is issued if the client is configured to have refresh tokens. This token can be used to obtain more access tokens once the first one expires. The refresh token may have a very long lifetime, ranging from hours to years.
The Authorization Endpoint Request
- Method:
GET - Agent: Browser
- Response Type: Redirect to pre-registered callback at client with query parameters
Request Parameters
| Parameter | Value | Mandatory | Description |
|---|---|---|---|
| client_id | The Client ID | yes | The ID of the requesting client |
| response_type | code | yes | Defines the flow type: authorization code flow |
| state | a random value | no | Will be provided back to the client in (4). Useful to keep track of the session in the client or to prevent unsolicited flows. |
| scope | Space separated string of scopes | no | List the scopes the client is requesting access to. |
| redirect_uri | The client callback URL | no* | The redirect_uri the client wants (4) to redirect to. *Mandatory if multiple redirect URIs are configured on the client. |
| code_challenge | A high entropy random challenge | no* | A challenge generated by the client, if sent, the code_verfier must be sent on the token call. *Required when client must do PKCE (RFC7636) |
| code_challenge_method | “plain” (default) or “S256” | no | Can be used if code_challenge is sent. Defaults to “plain”. Needs to be sent if S256 is used as code_challenge method. |
Additional Request Parameters
For additional request parameters refer to the OpenID Connect Authorization Code Flow.
Response
A redirect back to the “redirect_uri”. Response parameters are provided on the query string.
| Parameter | Value | Mandatory | Description |
|---|---|---|---|
| state | The same value as given in the request | yes* | The same value as the client sent in the request. Use to match request to the redirect response. *Mandatory if the state was sent in the request |
| iss | Issuer Identifier | yes* | The issuer identifier of the authorization server where the authorization request was sent to. *Mandatory if the authorization server supports the OAuth 2.0 Authorization Server Issuer Identifier specification |
| code | An Authorization Code | yes | An authorization code nonce, to be used in the token request. |
The Token Endpoint Request
Request Parameters
- Method:
POST - Content-Type:
application/x-www-form-urlencoded - Agent:
HTTP client - Response Type:
json
| Parameter | Value | Mandatory | Description |
|---|---|---|---|
| client_id | The Client ID | yes | The ID of the requesting client |
| client_secret | The client secret | yes* | The secret of the client. *Mandatory if client authentication is of type secret, and the authentication is not done using basic authentication |
| grant_type | authorization_code | yes | Tells the token endpoint to do the second part of the code flow. |
| code | The authorization code | yes | The code given in the response of the Authorization request |
| redirect_uri | The callback URL of the Client | no* | The same redirect URI as was sent in the authorize request. *Required if redirect_uri was sent in the authorize request. |
| code_verifier | The verifier that matches the code_challenge | no* | *Mandatory if code_challenge was used in the authorize request. |
Response
- Response Type:
application/json
| Parameter | Value | Mandatory | Description |
|---|---|---|---|
| access_token | A newly issued access token | yes | The resulting access token for the code flow |
| refresh_token | A newly issued refresh token | no | Only issued if the client is configured to receive refresh tokens |
| expires_in | Expiration in seconds | yes | The time to live of the access token in seconds |
| scope | Space separated string | no | If not present the requested scopes where issued. If present the issued scopes may differ from the requested scopes. |
| token_type | Bearer or other token type | yes | Describes how the token can be used. Most commonly Bearer token usage. |
Conclusion
The OAuth authorization code flow is the most popular OAuth flow, one that you should make yourself the most familiar with. It can be used in any type of client and you will typically use it when you have user interaction. The flow might seem complicated at first as it involves a few redirects and different calls to the authorization server but it is required to ensure compliance with standards and to implement strong security.
Jacob Ideskog
Identity Specialist and CTO at Curity
Join our Newsletter
Get the latest on identity management, API Security and authentication straight to your inbox.
Start Free Trial
Try the Curity Identity Server for Free. Get up and running in 10 minutes.
Start Free Trial
