OIDC Front-Channel Logout — Browser-Based Cross-Application Session Termination

In this tutorial, you will learn about OIDC Front. We cover key concepts, practical examples, and best practices to help you master this topic.

Front-channel logout in Openid Connect uses browser iframes to propagate logout notifications from the provider to all active client applications, ensuring that when a user logs out of one app, all other apps in the same SSO session also terminate.

What You'll Learn

• How front-channel logout propagates logout events via browser iframes
• How to implement a front-channel logout endpoint in your application
• Security considerations for iframe-based logout

Why It Matters

Without front-channel logout, when a user logs out of one application, the remaining applications still think the user is authenticated. The user must manually log out of each app. Front-channel logout automates this by having the provider load a logout iframe for each application.

Real-World Use

A user logs out of DodaMail. The provider renders a page that contains hidden iframes pointing to frontchannel_logout_uri for DodaDrive and DodaCalendar. Each iframe loads, clears its local session, and returns a transparent pixel. All three apps log out simultaneously.

sequenceDiagram
    participant User
    participant Provider as OIDC Provider
    participant Mail as DodaMail (iframe)
    participant Drive as DodaDrive (iframe)
    participant Calendar as DodaCalendar (iframe)

    User->>Provider: Logout Request
    Provider->>Mail: Load iframe (frontchannel_logout_uri)
    Provider->>Drive: Load iframe (frontchannel_logout_uri)
    Provider->>Calendar: Load iframe (frontchannel_logout_uri)
    Mail-->>Provider: 200 OK (1x1 pixel)
    Drive-->>Provider: 200 OK (1x1 pixel)
    Calendar-->>Provider: 200 OK (1x1 pixel)
    Provider-->>User: Logout Complete

Implementing Front-Channel Logout Endpoint

from flask import Flask, request, Response, session

app = Flask(__name__)

@app.route('/frontchannel_logout')
def frontchannel_logout():
    """Front-channel logout endpoint called by the OIDC provider via iframe"""
    # Clear the session
    session.clear()

    # Clear any cookies
    response = Response()
    response.set_cookie('session', '', expires=0)
    response.set_cookie('id_token', '', expires=0)

    # Return 1x1 transparent GIF (required by OIDC spec)
    response.data = (
        b'\x47\x49\x46\x38\x39\x61'
        b'\x01\x00\x01\x00\x80\x00'
        b'\x00\xff\xff\xff\x00\x00'
        b'\x00\x21\xf9\x04\x00\x00'
        b'\x00\x00\x00\x2c\x00\x00'
        b'\x00\x00\x01\x00\x01\x00'
        b'\x00\x02\x02\x44\x01\x00\x3b'
    )
    response.content_type = 'image/gif'
    response.headers['Cache-Control'] = 'no-cache, no-store, must-revalidate'
    response.headers['Pragma'] = 'no-cache'
    response.headers['Expires'] = '0'

    # Log the logout event
    app.logger.info(f"Front-channel logout processed for session")
    return response

Client-Side Front-Channel Handler

For SPAs that cannot rely on server-side session clearing alone:

// Client-side front-channel logout handler
window.addEventListener('load', function() {
  // Check if this page was loaded as a front-channel logout iframe
  const isLogoutIframe = window.location.pathname === '/frontchannel_logout';

  if (isLogoutIframe) {
    // Clear all client-side auth data
    localStorage.clear();
    sessionStorage.clear();

    // Notify the main window
    if (window.parent && window.parent !== window) {
      window.parent.postMessage('frontchannel_logout_complete', '*');
    }

    // Respond with a transparent pixel
    const pixel = new Image();
    pixel.src = 'data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7';
    document.body.appendChild(pixel);
  }
});

Configuring Front-Channel Logout URIs

{
  "client_id": "doda-browser",
  "redirect_uris": ["https://doda.example.com/callback"],
  "frontchannel_logout_uri": "https://doda.example.com/frontchannel_logout",
  "frontchannel_logout_session_required": true
}

The frontchannel_logout_session_required flag tells the provider whether to include the session ID in the logout request.

Common Mistakes

1. Returning Non-Image Content

The front-channel logout iframe must return a 1x1 transparent GIF or similar. Returning HTML or JSON may cause browser warnings.

2. Not Clearing Server-Side Session

The front-channel logout clears the client session but must also invalidate any server-side session tokens for complete security.

3. Ignoring SameSite Cookie Restrictions

If your session cookie uses SameSite=Strict, the iframe load from a different origin may not send cookies. Use SameSite=None with Secure or rely on the iss parameter instead.

4. Not Handling the iss Parameter

The provider may include an iss (issuer) query parameter. Validate it matches the expected provider before clearing the session.

5. Blocking iframe Loading with CSP

Your Content-Security-Policy may block the provider from loading your logout iframe. Ensure your CSP allows being embedded by the provider's origin.

Practice Questions

1. What does front-channel logout use to propagate logout events?
2. What content type should the front-channel logout endpoint return?
3. Why might SameSite cookie settings affect front-channel logout?
4. What is the iss parameter in front-channel logout?
5. How does front-channel logout differ from back-channel logout?

Answers

1. Browser iframes that load a logout URI for each application. 2. A 1x1 transparent GIF (image/gif). 3. SameSite=Strict cookies are not sent in cross-origin iframe requests. 4. The issuer of the logout request, which should be validated. 5. Front-channel uses browser iframes; back-channel uses server-to-server HTTP requests.

Challenge

Build a multi-application SSO system where logging out of any one application triggers front-channel logout across all applications. Include visual indicators showing which apps have acknowledged the logout and which are pending.

FAQ

Mini Project

Create a front-channel logout coordinator with a provider simulation that sends logout iframes to three registered applications. Each app implements the front-channel logout endpoint, logs the event, returns the pixel, and displays a real-time logout dashboard.

What's Next

• Learn about back-channel logout for server-to-server session termination
• Explore post-logout redirect URIs for user experience
• Continue to OIDC claims requests for fine-grained attribute control