OAuth 2.0 Flow

PasskeyBase uses the OAuth 2.0 Authorization Code flow with PKCE, the most secure flow for browser-based applications.

Why PKCE?

PKCE (Proof Key for Code Exchange, RFC 7636) protects the authorization code exchange without requiring a client secret. This is essential for single-page applications and native apps where a client secret cannot be kept confidential.

Sequence Diagram

Authorization Code + PKCE Flow

Step-by-Step Details

Authorization Request

The SDK generates a cryptographically random code_verifier, computes its SHA-256 hash as the code_challenge, stores the verifier in session storage, and redirects the user:

Authorization URL

https://myapp.auth.ing/authorize
  ?response_type=code
  &client_id=pk_live_abc123
  &redirect_uri=https://myapp.com/callback
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
  &scope=openid%20profile
  &state=random-state-value

Token Exchange

After the user authenticates and is redirected back with a code, the SDK exchanges it for tokens by sending the original code_verifier:

Token Request

POST https://myapp.auth.ing/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https://myapp.com/callback
&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
&client_id=pk_live_abc123

Token Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "id_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600
}

ID Token Claims

The ID token is a JWT containing claims about the authenticated user:

ID Token Payload (decoded)

{
  "iss": "https://myapp.auth.ing",
  "sub": "usr_abc123",
  "aud": "pk_live_abc123",
  "exp": 1717027200,
  "iat": 1717023600,
  "nonce": "random-nonce",
  "name": "Jane Doe",
  "email": "[email protected]"
}

Endpoints

Endpoint	Method	Description
`/authorize`	GET	Start the authorization flow
`/oauth/token`	POST	Exchange authorization code for tokens
`/userinfo`	GET	Get user profile with access token
`/logout`	GET	End the session
`/.well-known/openid-configuration`	GET	OIDC discovery document
`/.well-known/jwks.json`	GET	JSON Web Key Set for token verification