OAuth 2.0 Authorization Code Grant Flow

There are four steps involved in the authorization code grant, through which attackers can perform various authorization attacks on the API.

Step 1: Initiate Authorization Process

The user passes the GET request to the client via the user agent to initiate the authorization process. This operation can be performed via the "Login with" or "Connect" button displayed on the client's site.

Step 2: Redirect to Authorization Server

The user agent can be redirected to the authorization server by the client using the following parameters:

• response_type: Code used for informing the server which permissions to execute
• client_id: ID assigned to the client
• redirect_uri: URI where the authorization server redirects the user agent when the authorization code is provided
• scope: Defines the level of access to the application
• state: Opaque value used for security implementations

Step 3: Authorization Server Response

When the user is authenticated and authorized to access the resource, the user agent is redirected to redirect_uri by the authorization server. The server uses the following parameters to do this:

• code: Authorization code
• state: Value supplied in the previous request

Step 4: Request Access Token

Using the authorization code, the client requests the access token by adding the following parameters in the body of a request:

• grant_type: Authorization_code
• code: Authorization code received in the previous message
• redirect_uri: URI used in the first request

OAuth2 uses several key parameters depending on the flow and grant type. Here are the main parameters:

sequenceDiagram
    participant User as User
    participant UA as User Agent (Browser)
    participant Client as Client Application
    participant AS as Authorization Server
    participant RS as Resource Server

    Note over User, RS: OAuth 2.0 Authorization Code Grant Flow

    %% Step 1: Initiate Authorization
    User->>UA: Click "Login with" / "Connect" button
    UA->>Client: GET request to initiate authorization

    %% Step 2: Redirect to Authorization Server
    Client->>UA: Redirect to Authorization Server
    Note right of Client: Parameters:
- response_type: code
- client_id: [client_id]
- redirect_uri: [callback_uri]
- scope: [requested_scope]
- state: [random_value]
    
    UA->>AS: Authorization request with parameters
    AS->>User: Present login/consent page
    User->>AS: Authenticate & authorize

    %% Step 3: Authorization Server Response
    AS->>UA: Redirect to redirect_uri
    Note right of AS: Parameters:
- code: [authorization_code]
- state: [same_random_value]
    
    UA->>Client: Authorization code delivered

    %% Step 4: Request Access Token
    Client->>AS: POST request for access token
    Note right of Client: Body parameters:
- grant_type: authorization_code
- code: [authorization_code]
- redirect_uri: [same_callback_uri]
- client_id: [client_id]
- client_secret: [client_secret]
    
    AS->>Client: Access token response
    Note right of AS: Response:
- access_token
- token_type
- expires_in
- refresh_token (optional)

    %% Access Protected Resource
    Client->>RS: API request with access token
    RS->>Client: Protected resource data
    Client->>User: Display requested data

Authorization Code Flow Parameters

Authorization Request:

• response_type - Set to "code"
• client_id - Your application's client identifier
• redirect_uri - Where to redirect after authorization
• scope - Requested permissions (space-separated)
• state - CSRF protection token (recommended)
• code_challenge - For PKCE (optional but recommended)
• code_challenge_method - Usually "S256"

Token Request:

• grant_type - Set to "authorization_code"
• code - Authorization code from previous step
• redirect_uri - Must match the authorization request
• client_id - Your application's client identifier
• client_secret - Your application's secret (if confidential client)
• code_verifier - For PKCE

Other Grant Types

Client Credentials:

• grant_type - Set to "client_credentials"
• scope - Requested permissions
• client_id / client_secret - Application credentials

Refresh Token:

• grant_type - Set to "refresh_token"
• refresh_token - The refresh token
• scope - Optional, to request fewer permissions

Resource Owner Password (deprecated):

• grant_type - Set to "password"
• username / password - User credentials
• scope - Requested permissions

Common Response Parameters

Successful Token Response:

• access_token - The access token
• token_type - Usually "Bearer"
• expires_in - Token lifetime in seconds
• refresh_token - For getting new tokens
• scope - Granted permissions

Error Response:

• error - Error code (e.g., "invalid_grant")
• error_description - Human-readable description
• error_uri - Link to error documentation

The exact parameters and their requirements can vary between OAuth2 providers, so always check the specific API documentation you're working with.