Your suggested change has been received. Thank you.

close

Suggest A Change

https://thales.na.market.dpondemand.io/docs/dpod/services/kmo….

Thales Logo

All

  • All
back

OAuth 2.0 and OpenID Connect

iFrame session monitoring

search

iFrame session monitoring

The OneWelcome Identity Platform OpenID Connect Provider (OP) offers session monitoring with iFrames, a relying party iFrame, and an End Session endpoint for relying party-initiated logouts.

You can implement the Relying Party (RP) side of session management using two iFrames.

Include two iFrames on your website's HTML page that communicate back and forth, to determine whether the session state has changed. If it detects a change, the RP needs to make an authentication request with the request parameter prompt=none, to determine if the user is still logged in.

For more information, see the Session Status Change Notification specification.

Flow diagram

Session Monitoring

The steps described below occur when the session has already been established at the RP and OpenID Provider (OP).

  1. THe RP iFrame calls postMessage(), which sends data to the OP iFrame to check the session state.

  2. The OP iFrame responds changed, unchanged, or error depending on the current state. The (OP browser state matches what is expected.)

  3. Steps 1 and 2 occur at a specific interval to continue monitoring the session.

  4. When the session on the OP ends either via timeout or some user action, the state is changed to reflect it. (The OP browser state is updated.)

  5. Meanwhile, the RP iFrame continues to repeat step 1 and 2 and detects that something has changed.

  6. The RP makes an authentication request with prompt=none to the OP, to determine whether they are still authenticated.

  7. If so, the RP stores the new session_state and id_token values.

  8. If Step 6 results in a login_required error, the RP invalidates the RP session in their application and clears any local storage, such as idToken or session_state.

  9. The user is notified about the logout.

This scenario also supports multiple RPs that exist within the same user agent and share an OP, because the session can be valid for multiple RPs simultaneously. If one logs out, the checkStatus interval triggers the other to also log out.

Implementation as the RP

To monitor the session state of your users, you need to embed the two iFrames into your pages. Using the OneWelcome Identity Platform as the OP provides an endpoint to get the HTML for the OP iFrame. It is located on the OP server at /oauth/v1/checksession. You can see an example of the HTML with comments in OpenID Provider iFrame. The RP iFrame is responsible for calling the postMessage function of the OP iFrame with the necessary arguments.

Getting session_state from the authentication request

Example query string response on the authorization endpoint

?scope=openid&session_state=e25f178e1642c58da7be3d2066a546684bd6b8e4012ded2321d66bbe3e01b5f4.726095b8a2a71a7886c95496bf3910dc7ab374343eeef3e36e871cbee9360e71

When you make the authentication request to the OP, a session_state value is returned on the authorization endpoint. The RP first validates the ID token that is returned, and if valid, stores the session_state value from the query string. It must be stored so that the JavaScript in the RP iFrame is able to access it. It needs to send it to the OP iFrame as part of checking the session state.

Read more about creating and updating sessions.

Using a cookie to store the session state value is probably the most common approach, but it should be named uniquely to avoid being overwritten.

If the session_state value is modified locally, it triggers a status change, which results in network traffic because it is directly coupled to the browser state in the OP. Cookies are shared on a per-domain basis, so take extra care if you want to host multiple RPs on a single domain.

Relying party iFrame

A relying party iFrame needs to be created to communicate with the OP iFrame. For help with the implementation, see the example implementation with some comments.

Putting the two iFrames together

After the RP iFrame has been implemented, it is as simple as including both on a page that is authenticated.

Sample HTML for including both:

<iFrame id="rpif" style="width:0;height:0;border: 0;border: none;position:absolute;" src="https://RPserver.example.com/rpiFrame"></iFrame>
<iFrame id="opif" style="width:0;height:0;border: 0;border: none;position:absolute;" src="https://oneginiOPServer.example.com/oauth/v1/checksession'}"></iFrame>

Restrictions

Identity providers

The OneWelcome Identity Platform requires the identity provider to determine whether the user is still authenticated. For a JavaScript client that uses the authorization code flow with PKCE, you must use SAML artifact binding. For server-side relying party implementations, you can also use the SAML redirect or post binding.

When a different type of identity provider is used, the OneWelcome Identity Platform always responds with the error login_required.

Hosts and cookies

The request towards the OneWelcome Identity Platform requires a cookie to determine the session. To protect the privacy of their users, browsers no longer always send cookies to servers. The request to check the session with the OP is done via an iFrame, and this brings restrictions to the setup. Some browsers only send cookies to the OP when it shares the domain name with the RP and only via HTTPS.

When the RP is accessed on https://www.example.com, the OP must use a host name that ends with example.com. Browsers then send the cookies to https://oneginiOPServer.example.com, but not to https://oneginiOPServer.example.net.

Blocked iFrames

If you experience errors in the browser about the RP iFrame when testing, you might need to tweak the X-Frame-Options header in your application, to allow same-origin when serving an iFrame from your own domain.

If your RP sends a Content-Security-Policy response header, it must allow iFrames on its own host the host of the OP.

On this page