Skip to content
Connect2id

OpenID Connect check session iframe

1. Iframe-based IdP session monitoring

After signing in a user with OpenID Connect the client application may need to periodically check if the user is still logged in with the OpenID provider.

The basic method to silently check for that is by making an OpenID authentication request with the optional prompt=none parameter. This asks the server to return a new ID token without any user interaction, unless the user is no longer authenticated or client access was revoked (signalled by a login_required, consent_required or the catch-all interaction_required error).

An alternative method to check the user authentication status is provided by the OpenID Connect Session Management extension: After successful user authentication, the client application can use window.postMessage to poll a hidden iframe, where JavaScript with access to the IdP session cookie can check for changes in in the user’s authentication status.

Checking the session status with window.postMessage is efficient - there’s minimal client-server communication involved, the check is usually handled in browser JavaScript, and the required cryptography is lightweight too.

2. Prerequisites

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

For example:

{
  "iss"                  : "https://c2id.com",
  "check_session_iframe" : "https://c2id.com/check-session.html",
  ...
}

3. Usage

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

https://client.example.org/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://c2id.com/check-session.html" 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 000123 and the session_state returned above:

000123 1vO3YeeIlejo7VELPzUYetJ3Ovvpl9AA7sLIQyUEvBM.0N8wJYFjJ-tNyMTROxq4lg

The message posting to the check_session_iframe must fulfil 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 an https://client.example.com/callback redirection URI the message must be posted from JavaScript which has the https://client.example.com origin. If this condition isn’t met, the OpenID provider iframe will respond with a false “changed” result.

  • 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 message = client_id + " " + session_state;

// Post the message to the OpenID provider iframe
var idpOrigin = "https://c2id.com";
var targetWindow = document.getElementById("op").contentWindow;
targetWindow.postMessage(message, idpOrigin);

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.