Originally published at GeekCoding101.

Brief Description

The OAuth 2.0 authorization code flow is a secure and widely adopted method for obtaining access tokens to access user resources on behalf of the user.

Steps

Here's a summary of the steps in the authorization code flow:

1. Client Initiation: The client application initiates the authorization process by redirecting the user to the authorization server's authorization endpoint.

2. User Authentication and Consent: The user is prompted to authenticate with the authorization server and grant permission to the client application to access their resources.

3. Authorization Code Generation: Upon successful authentication and consent, the authorization server generates an authorization code and redirects the user back to the client application along with the authorization code.

4. Access Token Exchange: The client application exchanges the authorization code for an access token by making a request to the authorization server's token endpoint.

5. Access Token Usage: The client application uses the access token to access the user's protected resources, such as APIs or data endpoints.

To clarify, in the authorization code flow, the authorization endpoint issues an authorization code to the client application upon user consent, not an access token directly.

The Flow with Real Requests

Here is what each step looks like on the wire (RFC 6749 section 4.1, with PKCE from RFC 7636). The client is https://app.example.com, the authorization server is https://auth.example.com.

1. Redirect the user to the authorization endpoint. The client generates a random state (CSRF protection) and a random code_verifier, then sends the browser to:

GET /authorize?response_type=code
    &client_id=my-app
    &redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback
    &scope=openid%20profile%20orders.read
    &state=af0ifjsldkj
    &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
    &code_challenge_method=S256 HTTP/1.1
Host: auth.example.com

code_challenge is BASE64URL(SHA256(code_verifier)); the verifier itself stays with the client.

2. The user signs in and approves the requested scopes on the authorization server's own pages. The client never sees the password.

3. The server redirects back with a one-time code:

HTTP/1.1 302 Found
Location: https://app.example.com/callback?code=SplxlOBeZQQYbYS6WxSbIA&state=af0ifjsldkj

The client must check that state matches the value it generated before going further.

4. The client exchanges the code for tokens over a direct back-channel call:

POST /token HTTP/1.1
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic bXktYXBwOm15LXNlY3JldA==

grant_type=authorization_code
&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback
&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

The Authorization: Basic header carries the client ID and secret (see HTTP Basic Authentication Explained); a public client such as a single-page or mobile app has no secret and relies on PKCE alone.

5. The server returns the tokens:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA",
  "scope": "openid profile orders.read"
}

6. The client calls the API with Authorization: Bearer <access_token>, and uses the refresh token to get a new access token when it expires.

Why PKCE Is Now Recommended for Every Client

PKCE was first designed for mobile apps, which cannot keep a client secret. If an attacker intercepts the authorization code (for example through a malicious app registered for the same redirect URI), they still cannot redeem it, because the token endpoint demands the code_verifier that only the real client knows. The OAuth 2.0 Security Best Current Practice (RFC 9700) and the OAuth 2.1 draft now recommend PKCE for confidential server-side clients as well, and OAuth 2.1 drops the implicit flow entirely. See OAuth 2.0 Grant Types Explained for how the other grant types compare.

Why Authorization Code Flow Not Issue Access Token Directly?

The OAuth 2.0 authorization code flow is designed to enhance security and minimize certain risks associated with transmitting sensitive information, such as access tokens, through the user's browser or mobile device.

Here are some reasons why the authorization endpoint issues an authorization code instead of an access token directly:

1. Reduced Exposure of Access Tokens: Access tokens are sensitive pieces of information that grant access to the user's protected resources. By issuing an authorization code instead of an access token directly, the authorization server reduces the exposure of access tokens to potentially compromised user agents (such as web browsers or mobile apps). Since the authorization code is short-lived and can only be exchanged for tokens by the client application with its credentials, the risk associated with the interception of the authorization code is lower than if an access token were transmitted directly.

2. Separation of Concerns: Separating the authorization process into two steps—obtaining the authorization code and exchanging it for an access token—helps clarify the roles and responsibilities of different components in the OAuth 2.0 flow. The authorization endpoint is responsible for handling user consent and authentication, while the token endpoint is responsible for issuing access tokens based on valid authorization codes and client credentials. This separation enhances the security and maintainability of the OAuth 2.0 protocol.

3. Support for Additional Security Measures: The authorization code flow allows for the implementation of additional security measures, such as client authentication at the token endpoint using client credentials (client ID and client secret), which helps verify the identity of the client application before issuing access tokens. This adds an extra layer of security to the token issuance process and helps prevent unauthorized access to user resources.

Overall, by issuing an authorization code instead of an access token directly, the OAuth 2.0 authorization code flow aims to improve security, reduce exposure to sensitive information, and provide a clear separation of concerns in the authentication and authorization process.

Benefits of Authorization Code Flow

1. Enhanced Security: By separating the authorization and token exchange steps, it reduces the risk of exposing sensitive information, such as access tokens, during the authorization process.

2. User Consent: Users have control over which resources the client application can access, ensuring privacy and security.

3. Scalability: The authorization code flow is well-suited for a wide range of client types, including web applications, mobile apps, and desktop applications.

4. Refresh Token Support: It supports the use of refresh tokens, allowing clients to obtain new access tokens without requiring user interaction.

FAQ

What is the difference between the authorization code and the access token?

The authorization code is a short-lived, single-use value that travels through the browser and is useless on its own. The access token is the credential that calls the API, and it is only ever returned over the back-channel token request.

Should a single-page app use the authorization code flow?

Yes, with PKCE. The implicit flow that SPAs used to rely on returns the token in the URL and is deprecated by the OAuth 2.0 Security Best Current Practice.

What is the state parameter for?

It ties the callback to the request the client started, so an attacker cannot make the client accept a code from a different authorization (a CSRF attack on the callback).

How long does an authorization code live?

RFC 6749 recommends a maximum of 10 minutes, and most providers use much less. It can be redeemed once; a second attempt should make the server revoke the tokens already issued for it.