Home
Documentation
Documentation
Step 1: User Authentication (SSO)
Authenticate the user with the Identity Provider (IDP) via Single Sign-On to obtain an ID Token.
Prerequisite
You need a registered client before this step. If you haven't registered yet, see Register Your App. You'll need your client_id, client_secret, and a registered redirect_uri.
Authorization request
First, redirect the user to the IDP's authorization endpoint:
http
| Parameter | Required | Description |
|---|---|---|
client_id | Yes | Your registered client ID |
response_type | Yes | Must be code for authorization code flow |
scope | Yes | Space-separated scopes (must include openid) |
redirect_uri | Yes | Must match registered redirect URI |
state | Recommended | Random value to prevent CSRF attacks |
code_challenge | Recommended | PKCE challenge (SHA256 hash of verifier) |
code_challenge_method | Recommended | Must be S256 when using PKCE |
Using oidc-client-ts (Recommended)
Token response
After successful authentication, you'll receive:
JSON
ID Token claims
The ID Token is a JWT containing user information:
JSON
| Claim | Description |
|---|---|
iss | IDP URL |
sub | Unique user identifier |
aud | Your client ID |
exp | Expiration time |
iat | Issued at time |
email | User's email address |
name | User's display name |
The ID Token is used in the next step (Token Exchange) to obtain an ID-JAG. Store it securely and never expose it in URLs or server logs.
Error handling
| Error | Cause | Fix |
|---|---|---|
unauthorized_client | Client ID not registered | Verify client ID in registration |
invalid_request | Missing or invalid parameter | Check all required parameters |
access_denied | User denied consent | Handle gracefully, allow retry |
invalid_grant | Code expired or already used | Restart auth flow |
Security considerations
- Use PKCE: Always include
code_challengeandcode_challenge_method=S256in authorization requests, even for confidential clients. - Validate
state: Compare thestateparameter in the callback against the value you sent to prevent CSRF attacks. - Short-lived ID Tokens: ID Tokens expire in ~10 minutes. Exchange them promptly in Step 2; do not cache or store them long-term.
- Secure storage: Store tokens in memory or secure session storage. Never expose them in URLs or server logs.
Next step
Once you have the ID Token, proceed to Step 2: Token Exchange to exchange it for an ID-JAG.
On this page