Check Session iframe

Overview

The Check Session IFrame endpoint allows relying parties (RPs) to detect changes in the user’s authentication state at the Identity Provider (IdP). It is defined by the OpenID Connect Session Management specification. RPs embed this endpoint in a hidden <iframe> within their application. The RP can then periodically send postMessage requests to the iframe to check whether the user’s session at the IdP is still valid.

Another option to silently check that a user is stilled signed in is by making an authentication request with prompt=none parameter. This will return a new ID token without user interaction, unless the user is no longer authenticated.

Endpoint

The endpoint is advertised in the check_session_iframe in the metadata exposed by the discovery endpoint and typically is:

GET https://[BASE_URL]/connect/checksession

Parameters

This endpoint does not accept query parameters directly. Instead, communication happens through HTML5 postMessage between the RP’s hidden iframe and the IdP’s check session iframe.

Usage

  1. Obtain session_state:
  • When the RP receives an authorization response from the IdP, it will include a session_state value.
  • The RP stores this value for use in session checking.
  1. Embed the iframe:
    <iframe id="op-iframe"
            src="https://[BASE_URL]/connect/checksession"
            style="display:none;">
    </iframe>
  1. Send Messages:
  • The RP periodically (e.g., every few seconds) sends a message via postMessage to the iframe in the form:
client_id session_state
  • Example in JavaScript:
var iframe = document.getElementById("op-iframe").contentWindow; 
var clientId = "my-client-id"; 
var sessionState = "abc123xyz"; // from IdP authorization response 
setInterval(function() {
     iframe.postMessage(clientId + " " + sessionState,
                        "https://[BASE_URL]"); 
}, 5000);
  1. Receive Responses:

  • The IdP responds back to the RP window with one of the following values:

    • "unchanged" – The session is still valid.
    • "changed" – The session has changed (e.g., user logged out at IdP).
    • "error" – Invalid message format or unrecognized client.

  • Example listener:

window.addEventListener("message", function(e) {
     if (e.origin !== "https://[BASE_URL]") return;
     if (e.data === "changed") {
         // Trigger RP logout or silent reauthentication
     }
}, false);

Security Considerations

  • Always validate the origin of the postMessage to ensure it matches the IdP domain.
  • The iframe should never be visible to end users.
  • Applications should define a clear flow for handling "changed" responses (e.g., logout the user, refresh tokens, or re-initiate login).