Authorization Code Flow

The flow described in this documentation refers to the Authorization Code Flow, described in the official OpenID Connect documentation.

Overview

The authorization code flow returns an Authorization Code to the client, which can exchange it for an id_token and an access_token directly. This flow has the benefit of not exposing any tokens to the user_agent (user's browser) and possibly to malware with access to the user_agent.

Flow Diagram

┌─────────┐                                          ┌──────────────────┐
│ Client  │                                          │ Identity         │
│ (App)   │                                          │ Provider (IdP)  │
└────┬────┘                                          └──────┬───────────┘
     │                                                       │
     │ 1. Redirect to /authorize                            │
     │    with client_id, redirect_uri, scope               │
     ├──────────────────────────────────────────────────────>│
     │                                                       │
     │                                                       │ 2. User logs in
     │                                                       │<──────────────────┐
     │                                                       │                  │
     │                                                       │ 3. Authentication │
     │                                                       │    successful     │
     │                                                       │──────────────────>│
     │                                                       │                  │
     │ 4. Redirect to redirect_uri                           │                  │
     │    with authorization code                           │                  │
     │<──────────────────────────────────────────────────────┤                  │
     │                                                       │                  │
     │ 5. POST /api/token/v2                                │                  │
     │    with code, client_id, client_secret                │                  │
     ├──────────────────────────────────────────────────────>│                  │
     │                                                       │                  │
     │ 6. Returns id_token and access_token                 │                  │
     │<──────────────────────────────────────────────────────┤                  │
     │                                                       │                  │
     │ 7. Validate id_token                                 │                  │
     │    (iss, aud, exp, signature)                        │                  │
     │                                                       │                  │
     │ 8. Use tokens to access resources                    │                  │
     │                                                       │                  │

Detailed Steps

1. Authorization Request: Client redirects user to /authorize endpoint with required parameters
2. User Authentication: User logs in with credentials
3. Authorization Grant: System validates user and generates authorization code
4. Redirect with Code: User is redirected back to redirect_uri with authorization code
5. Token Exchange: Client exchanges authorization code for tokens via POST to /api/token/v2
6. Token Response: System returns id_token and access_token
7. Token Validation: Client validates the id_token (issuer, audience, expiration, signature)
8. Resource Access: Client uses tokens to access protected resources

Security Benefits

• Tokens are never exposed to the browser
• Authorization code is single-use and short-lived
• Server-to-server token exchange ensures security
• Token validation prevents tampering