Authorization Code

The authorization code grant is used when an application exchanges an authorization code for an access token.

Overview

This flow is for web applications with a server-side component that can securely store the client secret.

Flow Diagram

Authorization Request

GET /authorize

Redirect the user to the authorization endpoint.

Parameters

Parameter	Required	Description
response_type	Yes	Must be code
client_id	Yes	Your client identifier
redirect_uri	Yes	URL to redirect after authorization
scope	Yes	Space-separated scopes
state	Recommended	CSRF protection token

Example

GET https://auth.example.com/authorize?
  response_type=code
  &client_id=abc123
  &redirect_uri=https://app.example.com/callback
  &scope=openid%20profile%20email
  &state=xyz789

Response

User is redirected to redirect_uri with:

https://app.example.com/callback?code=AUTH_CODE_HERE&state=xyz789

Always verify the state parameter matches what you sent to prevent CSRF attacks.

Token Request

POST /token

Exchange the authorization code for tokens.

Headers

Header	Value
Content-Type	application/x-www-form-urlencoded
Authorization	Basic {base64(client_id:client_secret)}

Parameters

Parameter	Required	Description
grant_type	Yes	Must be authorization_code
code	Yes	The authorization code
redirect_uri	Yes	Same as authorization request

Example

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

grant_type=authorization_code
&code=AUTH_CODE_HERE
&redirect_uri=https://app.example.com/callback

Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2g...",
  "scope": "openid profile email"
}

Complete Example

Node.js

const express = require('express');
const crypto = require('crypto');

const app = express();

const CLIENT_ID = 'your_client_id';
const CLIENT_SECRET = 'your_client_secret';
const REDIRECT_URI = 'http://localhost:3000/callback';
const AUTHORITY_URL = 'https://auth.example.com';

// Step 1: Redirect to authorization
app.get('/login', (req, res) => {
  const state = crypto.randomBytes(16).toString('hex');
  req.session.state = state;

  const params = new URLSearchParams({
    response_type: 'code',
    client_id: CLIENT_ID,
    redirect_uri: REDIRECT_URI,
    scope: 'openid profile email',
    state: state
  });

  res.redirect(`${AUTHORITY_URL}/authorize?${params}`);
});

// Step 2: Handle callback
app.get('/callback', async (req, res) => {
  const { code, state } = req.query;

  // Verify state
  if (state !== req.session.state) {
    return res.status(400).send('Invalid state');
  }

  // Exchange code for tokens
  const credentials = Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString('base64');

  const tokenResponse = await fetch(`${AUTHORITY_URL}/token`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      'Authorization': `Basic ${credentials}`
    },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      code: code,
      redirect_uri: REDIRECT_URI
    })
  });

  const tokens = await tokenResponse.json();
  req.session.tokens = tokens;

  res.redirect('/profile');
});

Python

from flask import Flask, redirect, request, session
import requests
import secrets

app = Flask(__name__)

CLIENT_ID = 'your_client_id'
CLIENT_SECRET = 'your_client_secret'
REDIRECT_URI = 'http://localhost:5000/callback'
AUTHORITY_URL = 'https://auth.example.com'

@app.route('/login')
def login():
    state = secrets.token_urlsafe(16)
    session['state'] = state

    params = {
        'response_type': 'code',
        'client_id': CLIENT_ID,
        'redirect_uri': REDIRECT_URI,
        'scope': 'openid profile email',
        'state': state
    }

    return redirect(f"{AUTHORITY_URL}/authorize?{urlencode(params)}")

@app.route('/callback')
def callback():
    code = request.args.get('code')
    state = request.args.get('state')

    if state != session.get('state'):
        return 'Invalid state', 400

    token_response = requests.post(
        f"{AUTHORITY_URL}/token",
        data={
            'grant_type': 'authorization_code',
            'code': code,
            'redirect_uri': REDIRECT_URI
        },
        auth=(CLIENT_ID, CLIENT_SECRET)
    )

    session['tokens'] = token_response.json()
    return redirect('/profile')

Security Considerations

1. Always validate state - Prevents CSRF attacks

2. Use HTTPS - Never transmit tokens over HTTP

3. Store secrets securely - Never expose client_secret

4. Validate redirect_uri - Use exact match

5. Short-lived codes - Authorization codes expire quickly

Next Steps

• Authorization Code + PKCE - For public clients

• Refresh Tokens - Token renewal

• Token Response - Response format