IFrame Session Monitoring
This guide is designed to help you implement the Relying Party (RP) side of Session Management using two iFrames.
Explanation
At the core of it, there should be two iFrames included on your website's html page that are communicating back and forth to determine if the session state has
changed. If it detects a change, the RP will need to make an Authentication request with the request parameter prompt=none
to determine if the user is still
logged in. You can read the spec in further detail about Session Status Change Notification.
Diagram of flow
The steps described below will occur once the session has already been established at the RP and OP.
- RP iFrame calls postMessage() which sends data to the OP iFrame to check the session state.
- OP iFrame will respond
changed
,unchanged
,error
depending on the current state. (OP browser state matches what is expected) - Steps 1 and 2 will occur at a given interval to continue monitoring session.
- When the session on the OP ends either via timeout or some user action, the state is changed to reflect it. (OP browser state is updated)
- Meanwhile, the RP iFrame has continued to repeat step 1 and 2 and it will detect that something has changed.
- RP makes an Authentication request with
prompt=none
to the OP to determine if they are still authenticated. - If so, the RP should store the new
session_state
andid_token
values. - If Step 6 results in a
login_required
error, RP should invalidate the RP session in their application, clear any local storage (idToken, session_state). - End user notified of logout
This scenario also supports multiple RP's that exist within the same User Agent that share an OP as the session can be valid for multiple RPs simultaneously. If one logs out, the checkStatus interval will trigger the other to also log out.
Implementation as the Relying Party
You will need to embed the two iFrames into your pages to monitor the session state of your users. Onegini as the OP, has provided an endpoint to get the html
for the OP iFrame. It is located at /oauth/v1/checksession
of the OP server. 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 implicit flow on Authorization endpoint
?scope=openid&id_token={...}&session_state=e25f178e1642c58da7be3d2066a546684bd6b8e4012ded2321d66bbe3e01b5f4.726095b8a2a71a7886c95496bf3910dc7ab374343eeef3e36e871cbee9360e71
When making the authentication request to the OP, a session_state
value will be returned on the Authorization endpoint. The RP should first validate
the ID Token that is returned and if valid, store the session_state
value from the query string. It should be stored so that the javascript in the RP iFrame is
able to access it. It will need to send it to the OP iFrame as part of checking the session state.
Read more about creating and updating sessions.
Session State in a cookie
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 will trigger a status change resulting in network traffic as 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 wish to host multiple RPs on a single domain.
Relying Party iFrame
A Relying Party iFrame will need to be created to communicate with the OP iFrame. Refer to our example implementation with some comments to help with the implementation.
Putting the two iFrames together
Once 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>
X-Frame-Options
If you are experiencing errors in the browser about the RP iFrame when testing, you may need to tweak the X-Frame-Options
header in your application to allow
same-origin
when serving an iFrame from your own domain.