Identity & Access
Go back to website

Authentication

This article describes the OAuth 2.0 Authorization Code Flow with PKCE, detailing the steps, endpoints, request payloads, and responses for initiating and completing user authentication.

OAuth 2.0 Authorization Code Flow with PKCE

This document outlines the OAuth 2.0 Authorization Code Flow with PKCE, detailing the steps, endpoints, request payloads, and responses involved in initiating and completing user authentication without a client secret.

1. User Initiates OAuth Flow

Action: User Redirect to Authorization Server

Purpose: The user initiates the OAuth flow by redirecting to the authorization server to request authorization.

Redirection URL Format:

https://auth.example.com/authorize?client_id=client123&redirect_uri=https://app.example.com/callback&response_type=code&scope=openid profile email&code_challenge=challengeValue&code_challenge_method=S256

  • Parameters:

    • client_id: The ID of the client application (e.g., client123).

    • redirect_uri: The URI where the authorization server will send the user after authorization.

    • response_type: The type of response desired (e.g., code).

    • scope: The scopes requested (e.g., openid profile email).

    • code_challenge: A transformed value of the code_verifier (see step 3).

    • code_challenge_method: Method used to derive the code_challenge (typically S256).

2. Authorization Server Redirects to Authentication Server

Action: Redirect to Authentication Server

Purpose: After validating the initial request, the authorization server redirects the user to the authentication server to initiate authentication if the session cookie is present. If the session cookie is not present, all authentication steps must be completed before proceeding.

Redirection URL:

https://auth.example.com/authentication/start?client_id=client123&redirect_uri=https://app.example.com/callback&response_type=code&scope=openid profile email&code_challenge=challengeValue&code_challenge_method=S256

3. Initiate Authentication

Endpoint: POST /authentication/start

Purpose: Starts the authentication process, retrieves available authentication methods, and returns a session cookie.

Request Payload:

{
  "identifier": "user@example.com",
  "client_id": "client123",
  "redirect_uri": "https://app.example.com/callback",
  "response_type": "code",
  "scope": "openid profile email",
  "code_challenge": "challengeValue",
  "code_challenge_method": "S256"
}

Response:

{
  "session_id": "auth_session_123456",
  "available_methods": ["password", "sms", "email", "sso", "passkey", "whatsapp"],
  "required_steps": 2,
  "next_step": 1
}

Session Cookie: Upon successful initiation, the server sets a session cookie in the user's browser to track the authentication session. This cookie should be sent with subsequent requests to maintain the session context.

4. Check Authentication Status

Endpoint: GET /authentication/status

Purpose: Checks the current status of the authentication session based on the session cookie.

Query Parameters:

  • session_id: The ID of the authentication session (e.g., auth_session_123456).

Response:

{
  "session_id": "auth_session_123456",
  "status": "pending",
  "completed_steps": 0,
  "remaining_steps": 2,
  "next_step": 1
}

5. Perform Authentication Step

Endpoint: POST /authentication/authenticate

Purpose: Processes the specified authentication step based on the selected method.

Request Payloads for Different Authentication Methods:

  • Password Authentication:

    Endpoint: POST /authentication/authenticate

    Request Payload:

    {
  "session_id": "auth_session_123456",
  "method": "password",
  "username": "user@example.com",
  "password": "securepassword123",
  "client_id": "client123",
  "redirect_uri": "https://app.example.com/callback",
  "response_type": "code",
  "scope": "openid profile email",
  "code_challenge": "challengeValue",
  "code_challenge_method": "S256"
}

  • SMS Authentication:

    Endpoint: POST /authentication/authenticate

    Request Payload:

    {
  "session_id": "auth_session_123456",
  "method": "sms",
  "phone_number": "+1234567890",
  "client_id": "client123",
  "redirect_uri": "https://app.example.com/callback",
  "response_type": "code",
  "scope": "openid profile email",
  "code_challenge": "challengeValue",
  "code_challenge_method": "S256"
}

  • Email Authentication:

    Endpoint: POST /authentication/authenticate

    Request Payload:

    {
  "session_id": "auth_session_123456",
  "method": "email",
  "email": "user@example.com",
  "client_id": "client123",
  "redirect_uri": "https://app.example.com/callback",
  "response_type": "code",
  "scope": "openid profile email",
  "code_challenge": "challengeValue",
  "code_challenge_method": "S256"
}

  • SSO Authentication:

    Endpoint: POST /authentication/authenticate

    Request Payload:

    {
  "session_id": "auth_session_123456",
  "method": "sso",
  "provider": "google",
  "client_id": "client123",
  "redirect_uri": "https://app.example.com/callback",
  "response_type": "code",
  "scope": "openid profile email",
  "code_challenge": "challengeValue",
  "code_challenge_method": "S256"
}

  • Passkey Authentication:

    Endpoint: POST /authentication/authenticate

    Request Payload:

    {
  "session_id": "auth_session_123456",
  "method": "passkey",
  "challenge": "randomChallenge123",
  "response": {
    "id": "credentialId",
    "rawId": "base64EncodedRawId",
    "type": "public-key",
    "response": {
      "clientDataJSON": "base64EncodedClientData",
      "authenticatorData": "base64EncodedAuthData",
      "signature": "base64EncodedSignature",
      "userHandle": "base64EncodedUserHandle"
    }
  },
  "client_id": "client123",
  "redirect_uri": "https://app.example.com/callback",
  "response_type": "code",
  "scope": "openid profile email",
  "code_challenge": "challengeValue",
  "code_challenge_method": "S256"
}

  • WhatsApp Authentication:

    Endpoint: POST /authentication/authenticate

    Request Payload:

    {
  "session_id": "auth_session_123456",
  "method": "whatsapp",
  "phone_number": "+1234567890",
  "client_id": "client123",
  "redirect_uri": "https://app.example.com/callback",
  "response_type": "code",
  "scope": "openid profile email",
  "code_challenge": "challengeValue",
  "code_challenge_method": "S256"
}

Response:

{
  "session_id": "auth_session_123456",
  "status": "success",
  "completed_steps": 1,
  "remaining_steps": 1,
  "next_step": 2
}

6. Verify OTP (for SMS, Email, or WhatsApp)

Endpoint: POST /authentication/verify-otp

Purpose: Verifies the one-time password (OTP) received via SMS, email, or WhatsApp.

Request Payload:

{
  "session_id": "auth_session_123456",
  "otp": "123456",
  "client_id": "client123",
  "redirect_uri": "https://app.example.com/callback",
  "response_type": "code",
  "scope": "openid profile email",
  "code_challenge": "challengeValue",
  "code_challenge_method": "S256"
}

Response:

{
  "session_id": "auth_session_123456",
  "status": "success",
  "completed_steps": 2,
  "remaining_steps": 0,
  "next_step": null
}

7. Complete Authentication

Endpoint: POST /authentication/complete

Purpose: Confirms the completion of all required authentication steps.

Request Payload:

{
  "session_id": "auth_session_123456",
  "client_id": "client123",
  "redirect_uri": "https://app.example.com/callback",
  "response_type": "code",
  "scope": "openid profile email",
  "code_challenge": "challengeValue",
  "code_challenge_method": "S256"
}

Response:

{
  "session_id": "auth_session_123456",
  "status": "completed"
}

8. Redirect Back to Authorization Server

Endpoint: GET /authorize

Purpose: Redirects the user back to the authorization server to obtain an authorization code.

Query Parameters:

  • client_id: The ID of the client application (e.g., client123).

  • redirect_uri: The URI where the authorization server will send the authorization code.

  • response_type: The type of response desired (e.g., code).

  • scope: The scopes requested (e.g., openid profile email).

  • state: A unique state value to maintain state between the request and callback.

  • code_challenge: The previously used code challenge.

  • code_challenge_method: The method used to create the code challenge.

PreviousDashboardNextPage 5

Last updated