Skip to main content

Check Session iFrame

After a user signs in with OpenID Connect, your application may need to periodically check if the user is still authenticated. While you can use prompt=none with the authorization endpoint for this purpose, the Check Session iFrame provides a more efficient, real-time solution.

Overview​

The Check Session iFrame is part of the OpenID Connect Session Management extension. It allows your application to:

  • Check session status without full page redirects
  • Detect logout events in real-time
  • Use lightweight browser-based JavaScript instead of server round-trips

How It Works​

  1. Your application loads a hidden iframe pointing to cidaas's check session endpoint
  2. JavaScript in your application sends messages to the iframe using window.postMessage
  3. The iframe (which has access to the cidaas session cookie) checks the session status
  4. The iframe responds with the session status: unchanged, changed, or error

This approach is highly efficient because:

  • Minimal client-server communication
  • Checks are handled in browser JavaScript
  • Lightweight cryptography
  • No full page reloads or redirects

Note: This is an advanced feature. For simpler use cases, see Session Management for the prompt=none approach.

The Check Session iframe URL looks like this:

Check Session iframe URL: https://{baseurl}/session/check_session

Prerequisites​

Check session polling must be enabled in the cidaas server. The server will then advertise the iframe URL for handling window.postMessage requests in its OpenID provider metadata.

For example:

{
  "iss"                  : "https://<span class="baseurl"></span>",
  "check_session_iframe" : "https://<span class="baseurl"></span>/session/check_session",
  ...
}

Usage​

If check session support is enabled the cidaas server will return an extra session_state parameter in its OpenID authentication responses:

https://<span class="baseurl"></span>/cb?
 code=SplxlOBeZQQYbYS6WxSbIA
 &state=af0ifjsldkj
 &session_state=1vO3YeeIlejo7VELPzUYetJ3Ovvpl9AA7sLIQyUEvBM.0N8wJYFjJ-tNyMTROxq4lg

The session state is an opaque string where the OpenID provider has encoded the authentication status of the user at the instant when the OpenID authentication request was processed. The client application is not concerned with the string content.

The client app can check if the user’s authentication status has changed by loading a hidden iframe pointing to the check_session_iframe URL and sending a request to it via window.postMessage.

Example: hidden iframe to the OpenID provider check_session_iframe URL:

< iframe id="check-session-iframe" src="https://<span class="baseurl"></span>/session/check_session" style="display: none"/>

The check session message sent to the iframe is a string containing the client ID and the session state separated by white space:

[client_id] [session_state]

Example message for client_id cs3bj4hbhb1 and the session_state returned above:

cs3bj4hbhb1 1vO3YeeIlejo7VELPzUYetJ3Ovvpl9AA7sLIQyUEvBM.0N8wJYFjJ-tNyMTROxq4lg

The message posting to the check_session_iframe must fulfill the following:

  • The message must be posted from the exact same web origin (scheme, hostname, port) as the client redirect_uri to which the OpenID authentication response was delivered.For example, with a redirection URI https://example.com/callback, the message must be posted from JavaScript which has the same origin.. If this condition isn’t met, the OpenID provider iframe will respond with a false "changed" result.

https://<span class="baseurl"

  • window.postMessage includes a target origin parameter. This must be set to the web origin of the check_session_iframe, else the browser will not deliver the message.

Example JavaScript to post a check session message:

// Compose the message
var mes = client_id + " " + session_state;

// Post the message to the OpenID provider iframe
 var stat = "unchanged";
  var mes = client_id + " " + session_state;

  function check_session()
  {
    var targetOrigin = "https://<span class="baseurl"></span>";
    var win = window.parent.document.getElementById("op").
                contentWindow;
    win.postMessage( mes, targetOrigin);
  }

  function setTimer()
  {
    check_session();
    timerID = setInterval("check_session()",3*1000);
  }

  window.addEventListener("message", receiveMessage, false);

  function receiveMessage(e)
  {
    var targetOrigin = "https://<span class="baseurl"></span>";
    if (e.origin !== targetOrigin ) {return;}
    stat = e.data;

    if stat == "changed" then take the actions below...
  }

The check session iframe will respond by posting a simple string back to the client app window (the window.postMessage event source, to be precise):

  • unchanged — to indicate the user authentication status at the OpenID provider has not changed; the client app can make another check some time later (e.g. after a minute).
  • changed — to indicate that the user authentication status has changed, e.g. due to logout, an expired session or some other event; after this the client app can ask the user to re-authenticate with the OpenID provider.
  • error — if the posted message is malformed and the OpenID provider JavaScript couldn’t parse the client ID, session state and origin from it.

Response Values​

The check session iframe responds with one of three values:

  • unchanged — The user's authentication status has not changed. Your application can check again later (e.g., after a minute).
  • changed — The user's authentication status has changed (e.g., due to logout, expired session, or other event). Your application should prompt the user to re-authenticate.
  • error — The posted message was malformed and couldn't be parsed.

Implementation Example​

Here's a complete example of implementing check session polling:

// Set up the iframe
var iframe = document.createElement('iframe');
iframe.id = 'check-session-iframe';
iframe.src = 'https://your-domain.cidaas.de/session/check_session';
iframe.style.display = 'none';
document.body.appendChild(iframe);

// Get client_id and session_state from your authentication response
var client_id = 'your_client_id';
var session_state = 'session_state_from_auth_response';

// Compose the message
var message = client_id + ' ' + session_state;
var targetOrigin = 'https://your-domain.cidaas.de';

// Function to check session
function checkSession() {
  var iframeWindow = document.getElementById('check-session-iframe').contentWindow;
  iframeWindow.postMessage(message, targetOrigin);
}

// Set up message listener
window.addEventListener('message', function(event) {
  // Verify origin
  if (event.origin !== targetOrigin) {
    return;
  }
  
  var status = event.data;
  
  if (status === 'changed') {
    // User logged out or session expired
    // Redirect to login or show login prompt
    console.log('Session changed - user needs to re-authenticate');
    // Handle logout/redirect
  } else if (status === 'unchanged') {
    // Session still valid
    console.log('Session unchanged');
  } else if (status === 'error') {
    // Error occurred
    console.error('Check session error');
  }
}, false);

// Start polling (check every 3 seconds)
setInterval(checkSession, 3000);

Further Information​

The check session protocol is specified in OpenID Connect Session Management 1.0.

Need Support?​

Please contact us directly on our support page.