Session Management
Session management enables users to stay logged in across multiple applications and devices, providing a seamless authentication experience. This guide explains how sessions work in OAuth 2.0 and OpenID Connect, and how to implement session management in your applications.
What You'll Learn
- Basic concepts: sessions, tokens, and cookies
- How Single Sign-On (SSO) works
- Refresh tokens vs. session management
- How to check if a session is still valid
- How to properly end a session (logout)
Basic Concepts
Before diving into session management, it's important to understand these fundamental concepts:
| Term | Description | Configuration |
|---|---|---|
| Access Token | A short-lived token that grants access to protected resources. It expires after a configured time period. | Client-specific |
| Refresh Token | A long-lived token used to obtain new access tokens without requiring user re-authentication. | Client-specific |
| ID Token | A JWT token containing identity information about the authenticated user (OpenID Connect). | Client-specific |
| Session | A server-side record of a user's authenticated state, tied to a specific device and browser. Sessions are managed using cookies. | Instance-specific |
| Cookie | A small piece of data stored in the browser that identifies the user's session. | Browser-based |
Understanding Sessions
A session represents an authenticated user's state on the identity provider (cidaas). It's independent of any specific application and allows the user to access multiple applications without re-authenticating.
Sessions are:
- Device and browser-specific: Each browser on each device has its own session
- Time-limited: Sessions expire based on configured lifetime and inactivity settings
- Cookie-based: The session is maintained through HTTP cookies stored in the browser
Single Sign-On (SSO)
Single Sign-On allows users to authenticate once and access multiple applications without logging in again. This is the primary use case for session management in OAuth 2.0 and OpenID Connect.
How SSO Works
- User logs in to one application using cidaas
- cidaas creates a session and sets a cookie in the user's browser
- User visits another application that uses the same cidaas instance
- The application redirects to cidaas for authentication
- cidaas checks the session cookie - if valid, the user is automatically logged in
- cidaas redirects back to the application with tokens
Session Cookies
Session management in cidaas is based on HTTP cookies. A cookie contains:
- A unique session identifier
- The domain name (cidaas instance)
- Expiration information
Cookies enable websites to remember the user and keep them logged in across page refreshes and application switches.
Session Expiration
Sessions have two configurable expiration mechanisms:
| Setting | Description |
|---|---|
Session Lifetime (session_lifetime_in_seconds) | The maximum time a session can exist, regardless of activity. After this time, the session expires completely. |
Session Inactivity Timeout (session_inactivity_timeout_in_seconds) | The maximum time a session can remain inactive. If the user doesn't interact with any application for this duration, the session expires. |
What Causes Session Expiration?
| Event | Effect on Session |
|---|---|
| Logout | Session is invalidated immediately, cookies are removed |
| Password Reset | Session is invalidated by default (security measure) |
| Session Lifetime Expired | Session expires; user must re-authenticate |
| Inactivity Timeout | Session expires if no activity within the timeout period |
| Token Conditions (Prechecks) Not Met | Session cookies are reset until precheck requirements are fulfilled |
Remember Me
cidaas supports a "Remember Me" feature that extends session lifetime. When enabled:
- The default hosted pages send
rememberMe: trueduring login - If
rememberMeis not sent but the app settingis_remember_me_selectedis enabled, cidaas assumes the user should stay logged in - Passing
rememberMe: falseprevents the SSO cookie from being set, requiring re-authentication for each application
Refresh Tokens
Refresh tokens provide an alternative to session-based SSO, particularly useful for:
- Native mobile applications (Android, iOS)
- Desktop applications
- Smart devices and IoT
- Applications that need to work offline
Refresh Token vs. Session Management
| Aspect | Refresh Tokens | Session Management (SSO) |
|---|---|---|
| Use Case | Native apps, offline scenarios | Web applications, browser-based |
| Mechanism | Token-based | Cookie-based |
| Scope | Client-specific | Instance-wide (all apps) |
| Lifetime | Configurable per client | Instance-wide settings |
| Revocation | Per-token | Per-session (affects all apps) |
How to Get a Refresh Token
A refresh token is issued when you include the offline_access scope in your authorization request:
GET /authz-srv/authz?
response_type=code&
client_id=your_client_id&
redirect_uri=your_redirect_uri&
scope=openid profile offline_access
Using Refresh Tokens
When an access token expires, use the refresh token to get a new one:
API: Token Endpoint
Request:
POST /token-srv/token
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&
refresh_token=your_refresh_token&
client_id=your_client_id&
client_secret=your_client_secret
Important: After using a refresh token, a new refresh token is issued. The old refresh token cannot be reused (refresh token rotation).
Note: For most web applications, session-based SSO is recommended. Use refresh tokens primarily for native applications or scenarios where cookies cannot be used.
Validating Sessions
After a user signs in, your application may need to periodically check if the user is still authenticated. There are two main approaches:
1. Silent Authentication Check (prompt=none)
The simplest way to check session validity is to repeat the authorization request with prompt=none:
GET /authz-srv/authz?
response_type=code&
client_id=your_client_id&
redirect_uri=your_redirect_uri&
prompt=none
Response scenarios:
- Valid session: Redirects to
redirect_uriwithcodeortoken - Invalid/expired session: Redirects with
error=login_required
This approach works well for occasional checks but requires a full redirect flow.
2. Check Session iFrame (Advanced)
For more efficient, real-time session checking, you can use the OpenID Connect Session Management extension with an iframe. This allows JavaScript in your application to check session status without full page redirects.
See Check Session iFrame for detailed implementation.
3. Token Validation
To verify that tokens (access tokens, ID tokens) are valid and not expired, you need to:
- Validate the signature - Verify the token was issued by cidaas and hasn't been tampered with
- Check expiration - Ensure the token hasn't expired
- Verify claims - Confirm the token contains expected claims (audience, issuer, etc.)
See Validate Token for comprehensive information on JWT validation.
Ending Sessions (Logout)
When a user logs out, you need to properly end their session to ensure they're logged out from all applications. cidaas supports multiple logout mechanisms following OpenID Connect specifications.
See End Session (Logout) for complete information on implementing logout.
Related Topics
- OAuth2 Basics - Learn about OAuth 2.0 fundamentals
- Access Token / ID Token Claims - Understand token contents
- Validate Token - Deep dive into JWT validation
- Check Session iFrame - Advanced session checking
- End Session - Proper logout implementation
Need Support?
Please contact us directly on our support page.