# 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](broken://pages/7g0Zu0FHduTvKHgpoGNv) to see the technical details


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://oten.gitbook.io/identity-support/integration/understand-sso-flow/overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.