Authorization Code Flow

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Overview

The Authorization Code Flow is used to securely obtain an access token from an authorization server on behalf of a user. This flow is typically used in web applications where user authentication and consent are required.

When to Use

• Web applications with server-side backends
• Applications that need to access user data
• Scenarios requiring user authentication and consent

Getting a Client

You can create OAuth clients for the Authorization Code Flow in the Settings page of the Jiko authentication portal.

How It Works

1. The user initiates login by clicking a "Login" or "Authorize" button.
2. The application redirects the user to the authorization server.
3. The user authenticates and grants permission.
4. The authorization server redirects back with an authorization code.
5. The application exchanges the code for an access token.
6. The application uses the access token to access protected resources.

Authorization Request

The application redirects the user to the authorization endpoint with:

• response_type: Must be code
• client_id: The client identifier
• redirect_uri: Where to redirect after authorization
• scope: The requested scopes
• state: A random string to prevent CSRF attacks
• code_challenge: PKCE challenge (see PKCE)
• code_challenge_method: Must be S256

Request Example

GET /api/oauth2/authorize?response_type=code&client_id=your-client-id&redirect_uri=https://your-app.com/callback&scope=pockets.read&state=some-random-state&code_challenge=CODE_CHALLENGE&code_challenge_method=S256

Response Example

After the user authenticates and approves, the authorization server redirects back:

HTTP/1.1 303 See Other
Location: https://your-app.com/callback?code=authorization-code&state=some-random-state

Token Request

The application exchanges the authorization code for tokens by sending a request to the token endpoint with:

• grant_type: Must be authorization_code
• code: The authorization code received
• client_id: The client identifier
• client_assertion_type: Specifies the JWT format
• client_assertion: A signed JWT for client authentication (see Private Key JWT)
• code_verifier: The PKCE code verifier (see PKCE)

Request Example

POST /api/oauth2/token HTTP/1.1
Host: auth.jiko.io
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=authorization-code&
client_id=your-client-id&
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&
client_assertion=eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCJ9...&
code_verifier=CODE_VERIFIER

Response Example

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "dGhpcy1yZWZyZXNoLXRva2VuLi4u...",
  "token_type": "Bearer",
  "expires_in": 900
}

Access Token Lifetime

• Access tokens have a lifespan of 15 minutes.
• Refresh tokens have a lifespan of 90 days.
• Use the refresh token to obtain new access tokens without user re-authentication (see Refresh Tokens).

Security Considerations

• Always use PKCE to prevent authorization code interception attacks.
• Validate the state parameter to prevent CSRF attacks.
• Store tokens securely on the server side.
• Use short-lived JWTs for the client_assertion (recommended max 5 minutes).

📚 References

RFC 6749 - Authorization Code Grant - OAuth 2.0 Authorization Code Grant specification.

oauth.com - Detailed information and technical breakdowns.