Auth Flow

On this page

• Authorization Code + PKCE
• Client Credentials Flow
• Token Refresh
• MFA Flow
• JWT Structure
• OIDC Discovery

Authorization Code + PKCE

Recommended flow for all public clients (SPAs, mobile apps).

  Browser / SPA                  Gateway              Auth Service
      │                             │                      │
      │ 1. Generate code_verifier   │                      │
      │    code_challenge =         │                      │
      │    BASE64URL(SHA256(cv))    │                      │
      │                             │                      │
      │ 2. GET /auth                │                      │
      │    ?client_id=...           │                      │
      │    &response_type=code      │                      │
      │    &code_challenge=...      │                      │
      │    &code_challenge_method=  │                      │
      │      S256                   │──────────────────────►
      │    &scope=openid profile    │                      │
      │                             │                      │ 3. Show login page
      │◄────────────────────────────────────────────────── │
      │                             │                      │
      │ 4. User submits credentials │                      │
      │──────────────────────────────────────────────────► │
      │                             │                      │ 5. Validate password
      │                             │                      │    Issue auth_code
      │ 6. Redirect → callback?code=<auth_code>            │
      │◄────────────────────────────────────────────────── │
      │                             │                      │
      │ 7. POST /token              │                      │
      │    grant_type=              │                      │
      │      authorization_code     │                      │
      │    code=<auth_code>         │                      │
      │    code_verifier=<cv>       │──────────────────────►
      │                             │                      │ 8. Verify PKCE
      │                             │                      │    Issue tokens
      │ 9. { access_token,          │                      │
      │      refresh_token,         │◄─────────────────────│
      │      id_token }             │                      │
      │◄───────────────────────────  │                      │

Step-by-step

# Step 2 — redirect user to auth endpoint
https://localhost:8080/realms/master/protocol/openid-connect/auth
?client_id=opengate-console
&redirect_uri=http://localhost:3000/callback
&response_type=code
&code_challenge=<BASE64URL_SHA256_of_verifier>
&code_challenge_method=S256
&scope=openid+profile+email

# Step 7 — exchange code for tokens
curl -X POST http://localhost:8080/realms/master/protocol/openid-connect/token \
-d "grant_type=authorization_code" \
-d "code=<auth_code>" \
-d "redirect_uri=http://localhost:3000/callback" \
-d "code_verifier=<verifier>" \
-d "client_id=opengate-console"

Client Credentials Flow

For server-to-server communication (confidential clients):

  Backend Service              Gateway              Auth Service
      │                           │                      │
      │ POST /token               │                      │
      │ grant_type=               │                      │
      │   client_credentials      │──────────────────────►
      │ client_id=...             │                      │ Validate client secret
      │ client_secret=...         │                      │ Issue access_token
      │                           │◄─────────────────────│
      │◄──────────────────────────│                      │
      │ { access_token }          │                      │

curl -X POST http://localhost:8080/realms/master/protocol/openid-connect/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials" \
-d "client_id=my-backend-service" \
-d "client_secret=<secret>"

Token Refresh

curl -X POST http://localhost:8080/realms/master/protocol/openid-connect/token \
-d "grant_type=refresh_token" \
-d "refresh_token=<refresh_token>" \
-d "client_id=opengate-console"

MFA Flow

When mfaRequired: true is set on the realm:

  Client              Auth Service           MFA Service
    │                      │                     │
    │ 1. POST credentials  │                     │
    │─────────────────────►│                     │
    │                      │ 2. Password valid   │
    │ 3. { mfa_required:   │                     │
    │      true,           │                     │
    │      mfa_token }     │                     │
    │◄─────────────────────│                     │
    │                      │                     │
    │ 4. POST /mfa/totp/   │                     │
    │    verify            │                     │
    │    { totp_code,      │─────────────────────►
    │      mfa_token }     │                     │ 5. Verify TOTP
    │                      │◄────────────────────│
    │                      │ 6. Issue full tokens│
    │◄─────────────────────│                     │

JWT Structure

Access tokens are RS256-signed JWTs:

{
"iss": "http://localhost:8080/realms/master",
"sub": "usr_abc123",
"aud": ["opengate-console"],
"exp": 1705312800,
"iat": 1705309200,
"jti": "550e8400-e29b-41d4-a716-446655440000",
"realm": "master",
"email": "alice@example.com",
"email_verified": true,
"given_name": "Alice",
"family_name": "Smith",
"roles": ["admin", "user"]
}

OIDC Discovery

curl http://localhost:8080/realms/master/.well-known/openid-configuration

Key fields in the discovery document: