OpenID Connect Session Management

Why Relying Party(RP) need to check the login status of end user?

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.

Authentication request by RP

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 image 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

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 as changed.
  • 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 RP iframe

Pseudocode of OP iframe

Pseudocode of OP iframe

Piraveena Paralogarajah

Written by

Software Engineer @WSO2, CSE Undergraduate @ University of Moratuwa, Former Software Engineering Intern @ WSO2

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade