Overview

This section explains how Single sign-on works behind the scenes. Understanding this flow helps both developers implement SSO correctly and end users understand what's happening during login.

🎯 Learning objectives

After reading this section, you'll understand:

• The complete SSO authentication flow

• What happens at each step

• The role of different components

• How tokens work in SSO

• Security considerations

🏗️ SSO architecture overview

Key components

1. User's browser

• Where the user interacts with applications

• Handles redirects between application and IDP

• Stores session cookies (temporarily)

2. Your application

• Frontend: User interface, login buttons

• Backend: Handles OAuth flow, stores tokens securely

3. Oten IDP

• Identity Provider: Authenticates users

• Token Service: Issues and validates tokens

• User Store: Manages user accounts and profiles

Detailed step-by-step process

Step 1: User initiates login

User Action: Clicks "Login" button
Application: Checks if user is authenticated
Result: User needs to authenticate

Step 2: Generate PKCE parameters

Application: Generates code_verifier (random string)
Application: Creates code_challenge from code_verifier using SHA256
Application: Stores code_verifier for later use
Security: PKCE prevents authorization code interception

Step 3: Create JAR (JWT-Secured authorization request)

Application: Creates authorization parameters:
  - response_type: "code"
  - client_id: "your_client_id"
  - redirect_uri: "https://yourapp.com/callback"
  - scope: "openid profile email"
  - state: "random_state_string" (CSRF protection)
  - nonce: "random_nonce_string"
  - code_challenge: generated from step 2
  - code_challenge_method: "S256"

Application: Signs parameters as JWT using client_secret (HS256)
Security: JAR ensures request integrity and authenticity

Step 4: Redirect to authorization endpoint

Application: Creates authorization URL with JAR:
URL: https://account.oten.com/v1/oauth/authorize?client_id=your_client_id&request=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Browser: Redirects user to Oten IDP
Note: Traditional OAuth query parameters are NOT supported

Step 5: User authenticates at IDP

IDP: Validates JAR signature and parameters
IDP: Shows login form
User: Enters username/password
IDP: Validates credentials
Optional: Two-factor authentication
IDP: User grants consent for requested scopes

Step 6: IDP issues authorization code

IDP: Creates temporary authorization code (10-minute expiry)
IDP: Validates redirect_uri matches registered URI
Browser: Redirects back to application with code and state
URL: https://yourapp.com/callback?code=abc123&state=xyz789

Step 7: Handle callback and validate

Application: Parses callback parameters (code, state, error)
Application: Validates state parameter matches stored value
Application: Checks for authorization errors
Security: State validation prevents CSRF attacks

Step 8: Exchange code for tokens

Application: Sends POST request to token endpoint:
  - grant_type: "authorization_code"
  - code: received authorization code
  - redirect_uri: must match authorization request
  - client_id: application identifier
  - code_verifier: PKCE verifier from step 2
  - client_secret: for confidential clients

IDP: Validates code, client credentials, and PKCE verifier
IDP: Returns token response:
  - access_token: for API calls (1 hour expiry)
  - refresh_token: for token renewal (long-lived)
  - id_token: user information (JWT format)
  - expires_in: token lifetime in seconds

Step 9: Store and use tokens

Application: Stores tokens securely (sessionStorage for web apps)
Application: Extracts user info from ID token
Application: Uses access token for protected API calls
User: Successfully logged in and can access application

Step 10: Token management

Application: Monitors token expiration
Application: Automatically refreshes tokens using refresh_token
Application: Handles token refresh failures (redirect to login)
Application: Provides logout functionality (clears stored tokens)

🎫 Understanding tokens

Authorization code

• Purpose: Temporary code to exchange for tokens

• Lifetime: Very short (usually 10 minutes)

• Security: Single-use only

• Example: abc123def456ghi789

Access token

• Purpose: Grants access to protected resources

• Lifetime: Short (15-60 minutes)

• Format: Usually JWT (JSON web token)

• Usage: Sent with API requests

Refresh token

• Purpose: Obtains new access tokens

• Lifetime: Long (days to months)

• Security: Stored securely, can be revoked

• Usage: Automatic token renewal

ID token

• Purpose: Contains user identity information

• Format: JWT with user claims

• Contents: User ID, email, name, etc.

• Usage: Application knows who the user is

🔐 Security mechanisms

State parameter

• Purpose: Prevents CSRF attacks

• How it works: Random value sent and verified

• Implementation: Generated by app, validated on return

PKCE (proof key for code exchange)

• Purpose: Secures public clients (SPAs, mobile)

• How it works: Code challenge/verifier pair

• Required for: Applications that can't store secrets

Nonce

• Purpose: Prevents replay attacks

• How it works: Random value in ID token

• Usage: OpenID Connect flows

⏱️ Session management

Session lifecycle

1. Login: User authenticates, session created

2. Active: User accesses applications

3. Refresh: Tokens renewed automatically

4. Timeout: Session expires due to inactivity

5. Logout: User explicitly logs out

Session duration

• Access tokens: 15-60 minutes

• Refresh tokens: 7-30 days

• ID tokens: Same as access tokens

• SSO session: 8-24 hours (configurable)

Cross-application sessions

• Single logout: Logging out of one app logs out of all

• Session sharing: Login to one app grants access to others

• Centralized control: IT can revoke access globally

🔍 Monitoring and observability

What to monitor

• Login success/failure rates

• Token refresh patterns

• Session duration statistics

• Error rates by type

• Performance metrics

Logging best practices

• Log authentication events

• Don't log sensitive data (passwords, tokens)

• Include correlation IDs

• Monitor for suspicious patterns

🚨 Error scenarios

Common error flows

1. Invalid credentials: User enters wrong password

2. Expired code: Authorization code takes too long to exchange

3. Invalid client: Application not properly registered

4. Access denied: User cancels authentication

5. Server errors: IDP temporarily unavailable

Error handling strategy

• User-friendly messages: Don't expose technical details

• Retry mechanisms: Handle temporary failures gracefully

• Fallback options: Provide alternative authentication methods

• Monitoring: Alert on error rate spikes

---

Next: Dive deeper into the Flow diagram to see the technical details