OpenID Connect — Session Management

In my previous post, I talked about OpenID Connect and its basic workflows that are used to authenticate an End-User. Along with the login functionality, the logout functionality has to be provided as well to end the End-User’s session when required. The OIDC specification mentions the following three methods for Logout.

• Session Management
• Front-channel Logout
• Back-channel Logout

In this post, I will be elaborating on Session Management and how it works.

According to the specification,

Session Management is a method of monitoring the End-User’s login status at the OpenID Provider (OP) in a continuous basis so that the Relying Party (RP) can log out an End-User who has already logged out of the OP.

In simple terms, this means that in an implementation of OIDC Session Management, a Client application would constantly ask the Identity Provider supporting OpenID Connect, whether a particular End-User is still logged in. If the OP responds saying that the user is not logged in, the Client application would clear session data related to that user and log them out of the Client application.

So, why would an RP want to find out the login status of the End-User at the OP?

During OIDC login, an ID Token is used to authenticate the user. This ID Token comes with an expiration time. Hence, an RP may rely on that to log the user out when the ID Token expires. But, in an event where the user has logged out of the OP before the ID Token expires, the system becomes fragile.

Therefore, it is highly desirable for the RP to be able to find out the login status of the End-User at the OP.

How can this be achieved?

There are two ways by which an RP could check the login status of the End-User.

One method is to keep repeating the Authentication Request with prompt=none but this would cause too much network traffic and would disrupt or delay the service of the Authorization Server.

As it would be more desirable to check the login status without causing too much network traffic, a more improved technique involving iframes is used. Once the session for the End-User is established after a successful Authentication Request and Response, an RP iframe will keep polling an iframe on the OP for the login status of the End-User.

IFrames in Session Management

In SM, a pair of iframes is used on the OP side as well as the RP side. But first of all, what are iframes?

An iframe (short for inline frame) is an HTML element that allows an external webpage to be embedded in an HTML document.

An iframe in an HTML page would look like this.
<iframe src="URL"></iframe>
The src attribute is used to specify the URL of the external inline frame page.

In OIDC Session Management, the two iframes used are called RP iframe and OP iframe.

RP IFrame

This is an invisible iframe that the RP loads from within itself. This is the iframe that keeps polling the OP iframe with postMessage at regular intervals, therefore this iframe must know the ID of the OP iframe. It is also capable of receiving a postMessage back from the OP iframe and performing the relevant actions based on the postMessage content.

OP Iframe

This too is an invisible iframe that the RP loads from within the RP iframe using the check_session_iframe from the OP. This iframe has access to the Browser state at the OP and uses it to the re-calculate and compare with the OP session state sent by the RP to check if the session has changed since the last poll. This iframe can only accept postMessages from its parent iframe (i.e. RP iframe) and should reject postMessage request from any other source.

Prerequisites for Session Management

An OP supporting Session Management must return the following parameters.

1. session_state — This parameter should be returned in the Authentication Response. This is a JSON string that represents the End-User login status at the OP.
2. check_session_iframe — This must be included in the Server’s discovery response. This is the URL of the OP iframe.
3. end_session_endpoint — URL at the OP to which an RP can send logout requests. This also should be included in the Server’s discovery response.

How Session Management Works?

In OIDC, the RP session usually starts when the RP validates the End-User’s ID Token that is returned with the response from the OP Token Endpoint. The RP should have already obtained the check_session_iframe and end_session_endpoint from the OP’s Discovery response.

The typical Session Management flow would take place as follows.

• RP loads iframes from within itself.
• RP iframe polls OP iframe with postMessage at regular intervals with Client ID + " " + Session State.
• OP iframe accesses OP Browser State cookie and calculates new session_state and compares with the Session State sent by the RP. The OP Browser State cookie that is always updated by the OP in response to meaningful events such as logins, logouts, change of users, etc. Initially, this cookie will be sent by the OP to every RP sharing the same browser session and it will be stored in a database at the OP as well.
• OP iframe sends a postMessage to the RP iframe containing the session status as changed, unchanged or error.
• Upon receiving a postMessage back from the OP iframe, the RP iframe does one of the following. If the response is unchanged, the RP iframe does nothing. If the response is changed, RP must perform re-authentication with prompt=none to obtain a new ID Token. If no ID token is received, the RP carries out logout procedures for the End-User. If a new ID Token is received, the Session State of OP at the RP is updated and the End-User’s activity is continued. If the response is error, the error condition must be handled accordingly by the RP. Re-authentication must not be done in this instance as it would generate a lot of unnecessary network traffic.

What I have been talking about so far, is about what would happen if the End-User logs out of the OP directly or if the OP session times out (i.e. OP-initiated Logout). My next post will be about what happens when an End-User logs out of an RP or RP-initiated Logout.

Stay tuned!