Authorization Code Grant

Authorization Code Grant Study Guide

The Authorization Code Grant is one of the most secure and widely used OAuth 2.0 grant types. It is designed for applications that can securely store a client secret, typically server-side web applications, and involves a multi-step process where an authorization code is exchanged for an access token.

What is the Authorization Code Grant?

The Authorization Code Grant is an OAuth 2.0 flow that allows a client application to obtain an access token by first redirecting the user to an authorization server to authenticate and consent. The authorization server then issues an authorization code to the client, which is exchanged for an access token behind the scenes. This prevents exposure of tokens to the user agent (e.g., browser) and is considered more secure than implicit or other grant types.

Types of Applications That Implement Authorization Code Grant

• Server-Side Web Applications: Most common use case. The application runs on a web server with a backend that can securely store the client secret.
• Native Applications (Mobile/Desktop): Often used with Proof Key for Code Exchange (PKCE) to enhance security since client secrets can't be reliably stored in native apps.
• SPAs (Single Page Applications) with a Backend Component: If the SPA has a supporting server that can handle the token exchange securely.

Security Considerations

• Client Secret Confidentiality: The client secret must be stored securely on the server and never exposed to the client-side or public.
• Authorization Code Lifespan: Authorization codes should be short-lived (e.g., 10 minutes) to reduce the risk of interception and replay attacks.
• HTTPS Usage: All communications must occur over HTTPS to prevent man-in-the-middle attacks.
• Redirect URI Validation: The authorization server must validate the redirect URI to prevent authorization code leakage to malicious sites.
• PKCE (Proof Key for Code Exchange): Recommended for public clients (e.g., mobile apps) to mitigate authorization code interception attacks.
• Token Storage: Access and refresh tokens must be stored securely on the server and not exposed to the client unnecessarily.
• Scope Limitations: Applications should request only the minimum necessary scopes to limit potential damage if compromised.

Detailed Flow of Authorization Code Grant

Step 1: User Initiates Login/Authorization

• The user clicks a "Login" or "Authorize" button in the client application.
• The client constructs an authorization request URL and redirects the user to the authorization server.
• Example URL parameters:
  • response_type=code
  • client_id=abc123
  • redirect_uri=https://client.example.com/callback
  • scope=read write
  • state=random_string (for CSRF protection)

Step 2: User Authentication and Consent

• The authorization server presents a login page to the user.
• After authenticating, the user is shown a consent screen detailing the permissions (scopes) the client is requesting.
• The user approves or denies the request.

Step 3: Authorization Server Issues Authorization Code

• If the user approves, the authorization server redirects the user back to the client's redirect URI with an authorization code and the state parameter.
• Example redirect: https://client.example.com/callback?code=AUTH_CODE_HERE&state=random_string
• If the user denies, an error parameter is returned instead.

Step 4: Client Exchanges Authorization Code for Access Token

• The client application (server-side) makes a back-channel POST request to the authorization server's token endpoint.
• Request includes:
  • grant_type=authorization_code
  • code=AUTH_CODE_HERE
  • redirect_uri=https://client.example.com/callback
  • client_id=abc123
  • client_secret=SECRET_VALUE (if confidential client)

Step 5: Authorization Server Validates and Issues Tokens

• The authorization server validates the authorization code, client ID, client secret (if applicable), and redirect URI.
• If valid, it responds with an access token (and optionally a refresh token).
• Example response (JSON):
  • access_token: ACCESS_TOKEN_VALUE
  • token_type: Bearer
  • expires_in: 3600
  • refresh_token: REFRESH_TOKEN_VALUE (if included)

Step 6: Client Uses Access Token to Access Protected Resources

• The client includes the access token in the Authorization header when making requests to the resource server.
• Example: Authorization: Bearer ACCESS_TOKEN_VALUE
• The resource server validates the token and returns the requested data if authorized.

Step 7 (Optional): Refreshing Access Tokens

• If an access token expires, the client can use the refresh token to obtain a new access token without user interaction.
• Request to token endpoint:
  • grant_type=refresh_token
  • refresh_token=REFRESH_TOKEN_VALUE
  • client_id=abc123
  • client_secret=SECRET_VALUE (if confidential client)

Conclusion

The Authorization Code Grant is a robust and secure method for obtaining access tokens, especially for server-side applications. By keeping tokens out of the browser and using a back-channel exchange, it reduces the risk of token exposure. Proper implementation with security best practices—such as PKCE for public clients, strict redirect URI validation, and secure token storage—is essential for maintaining a secure OAuth 2.0 ecosystem.