OAuth 2.0 Design

Wrote docs/architecture/tasks/b2b-portal-auth-001/oauth-design/oauth-profile-spec.md. Complete OAuth 2.0 security profile specifying Authorization Code Grant with S256 PKCE, single-use refresh token rotation with breach detection, and ES256 JWT access tokens.

skill: oauth-design

OAuth 2.0 Profile Specification: B2B Partner Portal and Mobile [OAUTH-SEC-001]

Summary

This specification establishes the OAuth 2.0 security profile for Identity Platform v3.0 under run ID b2b-portal-auth-001.

It governs authentication and API authorization for public clients, including the Partner Web SPA and Mobile Apps, accessing the Core Banking API.

The profile rejects the deprecated Implicit Grant and mandates the Authorization Code Grant with mandatory Proof Key for Code Exchange (PKCE), using code_challenge_method=S256 exclusively.

The profile specifies

• 15-minute ES256-signed JWT access tokens
• Strict audience binding
• Single-use Refresh Token Rotation
• Automated refresh-token reuse detection and revocation cascades
• RFC 7009 token revocation

Detailed Description

Public clients cannot securely maintain client credentials. Historical OAuth implementations relied on the Implicit Grant, exposing access tokens in browser history, URI fragments, and HTTP Referer headers.

This profile conforms to the OAuth 2.0 Security Best Current Practice (BCP) and RFC 8252 (OAuth for Native Apps).

Criteria and Weights

Comparison

Result

Authorization Code Flow with PKCE (S256) is selected.

All public client token requests must use back-channel TLS exchanges.

Required Mechanisms

1. Authorization Flow and PKCE Parameters [MC-AF-01]

Authorization Request:

GET /realms/bank/protocol/openid-connect/auth?response_type=code&client_id=partner-web-spa&redirect_uri=https%3A%2F%2Fpartner.bank.com%2Fcallback&scope=openid%20partner%3Aaccounts%3Aread%20partner%3Atransfers%3Awrite&state=c3ab89d412e&code_challenge=E9Melhoa2OwvFrGMTJguCH5rtx64ZnVUq8_D3u5fc2k&code_challenge_method=S256 HTTP/1.1
Host: auth.bank.internal

Invariant: Authorization requests missing code_challenge_method or specifying plain are rejected with HTTP 400 invalid_request.

2. Token Exchange and Verification [MC-TE-01]

Token Request:

POST /realms/bank/protocol/openid-connect/token HTTP/1.1
Host: auth.bank.internal
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=partner-web-spa&code=SplxlOBeZQQYbYS6WxSbIA&redirect_uri=https%3A%2F%2Fpartner.bank.com%2Fcallback&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

The authorization server computes BASE64URL(SHA256(code_verifier)) and compares the result byte-for-byte with the stored code_challenge.

3. Token Profile and Scopes [MC-TP-01]

Access Token (JWT):

• Algorithm: ES256 (ECDSA using P-256 and SHA-256)
• Lifetime: 900 seconds (15 minutes)

Claims Schema:

4. Refresh Token Rotation and Breach Detection [MC-RR-01]

Refresh tokens are single-use artifacts with a 7-day sliding TTL and a 30-day absolute ceiling.

Rotation Cycle:

1. Client presents refresh_token_A.
2. Authorization server invalidates refresh_token_A.
3. Authorization server issues access_token_2 and refresh_token_B.

Breach Detection Cascade:

If an already-invalidated token (refresh_token_A) is presented again, the authorization server treats this as a token-reuse condition:

1. Detect the reuse condition.
2. Immediately revoke refresh_token_B and all descendant tokens associated with the session.
3. Invalidate the active user session.
4. Force complete re-authentication.

5. Revocation Endpoint (RFC 7009) [MC-RV-01]

Clients invoke

POST /realms/bank/protocol/openid-connect/revoke HTTP/1.1
Host: auth.bank.internal
Content-Type: application/x-www-form-urlencoded

token={token}&token_type_hint={token_type_hint}

upon user logout.

Invariants and Contracts

INV-OAUTH-01 — Prohibition of Implicit Grant

The Keycloak realm client configuration must have implicitFlowEnabled=false.

Any authorization request with response_type=token is rejected immediately.

INV-OAUTH-02 — Strict S256 PKCE Enforcement

Public clients must supply code_challenge_method=S256.

The authorization server must refuse code_challenge_method=plain or an omitted challenge method.

INV-OAUTH-03 — Audience Restriction

All access tokens emitted must carry

aud=https://api.bank.internal/v1

Core Banking API resource servers must reject access tokens lacking this exact audience claim.

Explicit Unknowns

• G-1: Hardware security module (HSM) key rotation schedule for ES256 signing keys in Keycloak.
• G-2: Native mobile app deep-linking constraints across Android App Links and iOS Universal Links.

Traceability

Verification

No validator was supplied, so no command was run.

Reviewer self-check against OAuth 2.0 Security BCP contracts:

• PKCE Verification: PASS. Requires code_challenge_method=S256; plain method forbidden.
• Grant Integrity: PASS. Authorization Code flow strictly required; implicit flow disabled.
• Rotation Mechanics: PASS. Single-use rotation with breach revocation cascades specified.
• Token Security: PASS. ES256 cryptographic signature and 15-minute expiration window enforced.

Open Decisions

DEC-OAUTH-01: Sarah Chen to determine whether a step-up MFA challenge is required when requesting scope partner:transfers:write.

Owner: Sarah Chen.

Next Steps

1. Marcus Vance configures Keycloak 24 realm clients, disabling implicit flow and enforcing PKCE S256.
2. Provide the frontend partner team with reference Authorization Code + PKCE integration library code.
3. Configure the Core Banking API gateway JWT validator to enforce ES256 signature validation and aud verification.