End Session (Logout)

When a user logs out of your application, you need to properly end their session with cidaas to ensure they're logged out from all applications using the same cidaas instance. This guide explains how to implement logout using OpenID Connect specifications.

Overview

Logout (also called "end session") is the process of terminating a user's authenticated session. In OpenID Connect, logout involves:

1. Initiating logout - Your application requests logout from cidaas
2. Ending the session - cidaas invalidates the user's session and removes cookies
3. Notifying other applications - Other applications using the same session are informed of the logout

The OpenID Connect specification defines three mechanisms for logout:

Specification	Purpose	How It Works
Relying Party Initiated Logout	Your application triggers logout	Redirects user to cidaas logout endpoint
Front-Channel Logout	Notify applications via browser	Renders logout iframe in each application
Back-Channel Logout	Notify applications via server-to-server	POST request to application's logout endpoint

Logout Endpoint

The logout endpoint URL is available in the OpenID Connect Discovery document:

Endpoint: https://your-domain.cidaas.de/session/end_session

You can find this endpoint in the end_session_endpoint field of the OpenID Configuration response.

Supported Methods: Both GET and POST are supported, following OpenID Connect specifications.

Initiating Logout

To log out a user, redirect them to the logout endpoint with the appropriate parameters. You can use either GET (for redirects) or POST (for form submissions).

Redirection After Logout

After logout, cidaas redirects the user to the post_logout_redirect_uri if:

• The URI is provided in the logout request
• The URI is registered in your app's allowed_logout_urls configuration

If no redirect URI is provided or it's not allowed, the user stays on the cidaas logout confirmation page.

Example Logout Requests

GET Request (Recommended for redirects):

GET https://your-domain.cidaas.de/session/end_session?
  id_token_hint=previously_issued_jwt_id_token&
  post_logout_redirect_uri=https://your-app.com/loggedout&
  state=random-state-value

POST Request (Alternative):

POST https://your-domain.cidaas.de/session/end_session
Content-Type: application/x-www-form-urlencoded

id_token_hint=previously_issued_jwt_id_token&
post_logout_redirect_uri=https://your-app.com/loggedout&
state=random-state-value

Using Access Token (Less Secure with GET):

GET https://your-domain.cidaas.de/session/end_session?
  access_token_hint=previously_issued_access_token&
  client_id=your-client-id&
  post_logout_redirect_uri=https://your-app.com/loggedout

Note: When using GET method with access_token_hint, it's recommended to use id_token_hint instead for better security. The system will log a warning if access_token_hint is used with GET method.

Session Cookie Fallback: If no token hints are provided, the endpoint will attempt to use the cidaas_sso session cookie if present. However, at least one of the following must be provided:

• id_token_hint or access_token_hint
• cidaas_sso session cookie

Logout Parameters

Parameter	Required	Description
id_token_hint	RECOMMENDED	The ID token previously issued to your application. This helps cidaas identify which user session to end.
post_logout_redirect_uri	OPTIONAL	Where to redirect the user after logout. Must be registered in your app's allowed_logout_urls.
state	OPTIONAL	An opaque value to maintain state between the logout request and the redirect callback.
client_id	OPTIONAL	Your OAuth 2.0 client identifier. Required if post_logout_redirect_uri is used without id_token_hint.
logout_hint	OPTIONAL	A hint about the user logging out (e.g., email, username). Similar to login_hint but for logout.
access_token_hint	OPTIONAL	The access token previously issued. Can be used instead of id_token_hint to identify the session.
ui_locales	OPTIONAL	Preferred languages for the logout UI (space-separated BCP47 language tags, e.g., "fr-CA fr en").

Front-Channel Logout

Front-channel logout notifies other applications about logout using browser-based communication. When a user logs out:

1. cidaas identifies all applications that share the user's session
2. For each application with frontchannel_logout_uri configured, cidaas renders an iframe
3. The iframe loads the application's logout endpoint
4. The application can then clear its local session state

Configuration: Set frontchannel_logout_uri in your app settings in the cidaas Admin UI.

Back-Channel Logout

Back-channel logout notifies applications via server-to-server communication. This is more reliable than front-channel logout because it doesn't depend on browser iframes and works even when the user's browser is closed.

How Back-Channel Logout Works

When a user logs out via the /session/end_session endpoint:

1. cidaas identifies all applications that share the user's SSO session (same sso_id/track_id)
2. For each unique application with backchannel_logout_uri configured, cidaas makes an asynchronous POST request
3. The request includes a logout_token (a JWT) that identifies the logout event
4. Your application validates the token and clears the user's session
5. The logout notification is sent asynchronously (non-blocking) to avoid delaying the user's logout flow

Back-Channel Logout Configuration in App Management

To enable back-channel logout for your application, configure the following in your app settings:

Setting	Description	Required
backchannel_logout_uri	The endpoint in your application that will receive logout notifications. Must be a publicly accessible HTTPS URL.	Yes (to enable back-channel logout)
backchannel_logout_session_required	If set to true, the logout token will include the sid (session ID) claim. This helps identify which specific session was logged out.	No (default: false)

Configuration Steps:

1. Navigate to your app settings in the cidaas Admin UI
2. Find the "Logout Settings" or "Session Management" section
3. Set the backchannel_logout_uri to your application's logout notification endpoint
4. Optionally enable backchannel_logout_session_required if you need session-specific logout handling

Back-Channel Logout Request

When a logout occurs, cidaas sends a POST request to your configured backchannel_logout_uri:

Aspect	Details
Method	POST
URL	Your app's backchannel_logout_uri (configured in app settings)
Content-Type	application/x-www-form-urlencoded
Body	logout_token=<JWT>
Timeout	1 second (non-blocking, failures are logged but don't affect the logout flow)

Logout Token Structure

The logout_token is a JWT that contains the following claims:

{
  "iss": "https://your-domain.cidaas.de",
  "sub": "user-subject-identifier",
  "aud": "your-client-id",
  "iat": 1234567890,
  "jti": "unique-token-id",
  "events": {
    "http://schemas.openid.net/event/backchannel-logout": {}
  },
  "sid": "session-id-123"  // Only included if backchannel_logout_session_required is true
}

Token Claims:

• iss (Issuer): The cidaas domain that issued the token
• sub (Subject): The user's subject identifier who logged out
• aud (Audience): Your application's client ID
• iat (Issued At): Timestamp when the token was issued
• jti (JWT ID): Unique identifier for this logout token
• events: Contains the back-channel logout event identifier
• sid (Session ID): The session identifier (only if backchannel_logout_session_required is enabled)

Validating the Logout Token

Your application should validate the logout token similarly to how you validate ID tokens:

1. Verify the signature using your app's public key or JWKS endpoint
2. Check the iss claim matches your cidaas domain
3. Check the aud claim matches your client ID
4. Verify the events claim contains http://schemas.openid.net/event/backchannel-logout
5. Check token expiration (if exp claim is present)
6. Validate the sid claim (if present) matches a known session in your application

Example Back-Channel Logout Handler

// Example Node.js/Express handler
app.post('/backchannel-logout', async (req, res) => {
  const { logout_token } = req.body;
  
  try {
    // Decode and validate the logout token
    const decoded = jwt.verify(logout_token, publicKey, {
      issuer: 'https://your-domain.cidaas.de',
      audience: 'your-client-id'
    });
    
    // Verify the logout event
    if (!decoded.events || !decoded.events['http://schemas.openid.net/event/backchannel-logout']) {
      return res.status(400).send('Invalid logout token');
    }
    
    // Clear the user's session
    const userId = decoded.sub;
    const sessionId = decoded.sid; // If backchannel_logout_session_required is enabled
    
    // Remove session from your application's session store
    await clearUserSession(userId, sessionId);
    
    res.status(200).send('OK');
  } catch (error) {
    console.error('Error processing back-channel logout:', error);
    res.status(400).send('Invalid logout token');
  }
});

Important Notes

• Asynchronous Processing: Back-channel logout requests are sent asynchronously and don't block the user's logout flow
• Timeout Handling: Requests have a 1-second timeout. Failures are logged but don't prevent logout
• Multiple Applications: If a user is logged into multiple applications with the same SSO session, all configured backchannel_logout_uri endpoints will receive notifications
• Security: Always validate the logout token signature and claims before clearing sessions
• HTTPS Required: The backchannel_logout_uri must be accessible via HTTPS

For detailed implementation, see the OpenID Connect Back-Channel Logout specification.

---

Related Topics

• Session Management - Understanding how sessions work
• Check Session iFrame - Detecting logout events in real-time
• Validate Token - How to validate logout tokens

Need Support?

Please contact us directly on our support page.