Check session iframe

1. Purpose

The Session Management Spec describes how the Relying Party (RP) obtains security session state from the OP and communicates a logout request to the OP. From the spec, “This specification complements the OpenID Connect Core 1.0 [OpenID.Core] specification by defining how to monitor the End-User’s login status at the OpenID Provider on an ongoing basis so that the RP can logout an End-User who has logged out of the OpenID Provider.”

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.

Core OpenID Connect enables clients to silently check for that, by repeating the original OpenID authentication request with the optional prompt=none parameter appended to it. This instructs 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).

A simpler alternative for checking 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 OpenID provider iframe, where JavaScript with access to the Identity Provider session cookie can check for changes in the user’s authentication status.

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

The Check Session iframe URL looks like this:

Check Session iframe URL: https:///session/check_session

OpenID Connect Session Management:

In OpenID Connect (OIDC), ID token comes with an expiry time. So some of us may think that Relying Parties will automatically terminate the end user’s session. But, it is entirely possible that the End-User might have logged out of the OpenID Provider before the expiration time.

Therefore, it is highly desirable to be able to find out the login status of the End-User at the OpenID Provider(OP).

How RP can check the end user’s login status?

In OIDC, there are some ways to check the login status of the end user.

1 . By using prompt=none as a request parameter in authentication request.

When RP sends authentication request to OP, it will send prompt=none as a parameter.

Example of the authentication request sent by RP is shown in the image below.

If prompt=none, Then Authorization Server MUST NOT display any authentication or consent user interface pages. An error is returned if an end-user is not already authenticated. The error code will typically be login required, interaction required.

So OP can use this as a method to check the login status of the end user. When RP sends an authentication request and returns an error code, the RP can consider that the end user is logged out from the OP.

But this is problematic. RP should send authentication request in a particular interval of time and OP should send the respond. This causes network traffic. So this is not the best way to check end user’s login status.

2 . By using hidden RP iframe polling the OP iframe

Since there is no an better way to check the end user’s login status, OpenID connect Session Management spec gives a better solution for this issue.

OpenID Connect Session Management specification, defines a way for RP to monitor the login status of an end user with an OP minimizing the network traffic.

How RP will discover the endpoints related to the Session management?

Endpoint is an interface exposed by communication party. So the messages to a communication party will reach that endpoint to communicate. To support OpenID Connect session management, the RP needs to obtain the session management related endpoint-URLs. These URLs are normally obtained via the OP’s Discovery response, as described in OpenID Connect Discovery 1.0.

There are two main endpoints used in OIDC Session management.

1 . OIDC logout endpoint

2 . OIDC Session iframe endpoint

OIDC logout endpoint

https://<IS_SERVER_HOST>:<IS_SERVER_PORT>/oidc/logout
Ex: https://localhost:9443/oidc/logout

By invoking this endpoint, a RP can notify the OP to logout an end user from the OP.

OIDC Session iframe endpoint

https://<IS_SERVER_HOST>:<IS_SERVER_POST>/oidc/checksession?client_id=<CLIENT_ID>
Ex: https://localhost:9443/oidc/checksession?client_id=2PX8XTppZBa6FYRZ6wqFs_o0mGYa

This endpoint provides the OP iframe, that supports session state synchronization with RP client via HTML5 postMessage API.

Role of Iframes in OIDC session management

The IFrame HTML element is often used to insert content from another source, such as an advertisement, into a Web page.

An example for iframe

The specification proposes the use of two iframes.

1 . RP iframe 2 . OP iframe

RP iframe

RP loads an invisible iframe from itself. This is at RP side. This iframe MUST assign an ID to the OP iframe, so that it can post message to the OP iframe.

A RP iframe will look like the below.

an RP iframe

OP iframe This iframe is at OP side. When RP sends post message to OP iframe using OIDC Session iframe endpoint, then OP iframe will respond to that message.

How OIDC Session Management works?

Session State

In OIDC Session management, a variable called session_state plays an important role. This session_state value is based on a salted cryptographic hash of Client ID, origin URL, and OP browser state.

an example for session_state value

https:///cb?
 code=SplxlOBeZQQYbYS6WxSbIA
 &state=af0ifjsldkj
 &session_state=1vO3YeeIlejo7VELPzUYetJ3Ovvpl9AA7sLIQyUEvBM.0N8wJYFjJ-tNyMTROxq4lg

Lets see how this OIDC session management works.

  • In OpenID Connect, the session at the RP typically starts when the RP validates the End-User’s ID Token.

  • OP Browser State is maintained by a cookie, called ‘opbs’ ( We can set any name for this OP Browser state cookie. Here I use ‘obps’ for OP Browser state cookie). When session starts, OP will send the obps cookie to the RP. So all the RPs sharing the same browser session will have the same obps cookie and the OP server will store that in a database for the particular browser session.

Lets see how this OIDC session management works.

  • In OpenID Connect, the session at the RP typically starts when the RP validates the End-User’s ID Token.

  • OP Browser State is maintained by a cookie, called ‘opbs’ ( We can set any name for this OP Browser state cookie. Here I use ‘obps’ for OP Browser state cookie). When session starts, OP will send the obps cookie to the RP. So all the RPs sharing the same browser session will have the same obps cookie and the OP server will store that in a database for the particular browser session.

  • When the OP supports session management, OP MUST also return the Session State as an additional session_state parameter in the Authentication Response. session_state= hash(client_id+obps cookie value+ callback url). So RP needs to store this session_state value. The way of storing the session_state value depends on the implementation of RP.

  • Then the polling mechanism between RP iframe and OP iframe starts after RP sends session_state value in the authentication response. The RP iframe polls the OP iframe with postMessage at an interval suitable for the RP application. With each postMessage, it sends the session state.

  • The post message from RP iframe : Client ID + “ “ + Session State. This message will be sent by RP to the OIDC Session iframe endpoint to trigger the OP iframe.

  • Then OP iframe will receive this post message by RP iframe. It accesses the obps value at the server and recalculate the session_state using the client_id, call-back-url and obps cookie value and compare it with the OP session state that was passed by the RP.

  • In OIDC Session management, when an end user logs out an RP , the RP will send a logout request to the logout endpoint of the OP. So OP server will remove the end user session value from the database and will terminate the session of the browser.

  • If the session is terminated, then obps cookie value will be changed. So when another RP sends post message with session_state value, then OP recalculates the session_state value for a particular RP. So it won’t be equal to the previous session_state value sent to the corresponding RP.

  • The OP will compare the session_state sent by the RP and the session_value calculated by itself. If both are equal, then OP will send response as not changed. If they are not equal, OP will send response aschanged.

  • When an RP terminates the browser session, then OP will send ‘not equal’as a response to the post messages of other RPs.

  • If OP sends changed, then other RPs should re-authenticate with prompt=none and id_token_hint=old ID token. If the received message is error, then RP should not re-authenticate and handle that as a logout of the end user.

  • So this OIDC Session management mechanism will notify the RPs about the session of the end-users without causing much network traffic.

OIDC Session management

Pseudocode for RP Iframe

Pseudocode of OP iframe

results matching ""

    No results matching ""