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.
- 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.
- OIDC logout endpoint
- OIDC Session iframe endpoint
OIDC logout endpoint
By invoking this endpoint, a RP can notify the OP to logout an end user from the OP.
OIDC Session iframe endpoint
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.
The specification proposes the use of two iframes.
- RP iframe
- OP 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.
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?
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.
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.
Pseudocode for RP Iframe
Pseudocode of OP iframe