Session management APIs
These APIs deal with OpenID Connect Session Management 1.0. The OneWelcome Identity Plaform OpenID Connect Provider (OP) offers the check session endpoint and a relying-party-initiated logout endpoint as part of session management.
The URls for check_session_iframe and end_session_endpoint are found in the Discovery API.
The two APIs are outlined here:
For more information on the implementation and configuration, refer to session management.
OpenID provider iFrame
The OpenID Provider (OP) iFrame is used in coordination with the Relying Party (RP) iFrame to keep track of the session state with the OP.
Endpoint: GET /oauth/v1/checksession
Example OP iFrame HTML response
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Check session</title>
<!-- necessary crypto libs included -->
<script>
window.addEventListener('message', receiveMessage, false);
function receiveMessage(e) {
if (document.referrer.lastIndexOf(e.origin, 0) !== 0) {
return;
}
if (typeof e.data !== 'string') {
postStatus(e, 'error');
return;
}
var messageTokens = e.data.split(' ');
var clientId = messageTokens[0];
var sessionState = messageTokens[1];
if (typeof sessionState === 'undefined') {
postStatus(e, 'error');
return;
}
var salt = sessionState.split('.')[1];
if (typeof salt === 'undefined') {
postStatus(e, 'error');
return;
}
var calculatedSessionState = calculateSessionState(clientId, e.origin, salt);
var status = (sessionState === calculatedSessionState) ? 'unchanged' : 'changed';
postStatus(e, status);
}
function postStatus(e, stat) {
e.source.postMessage(stat, e.origin);
}
function calculateSessionState(clientId, origin, salt) {
var opBrowserState = getOpBrowserState();
return CryptoJS.SHA256(clientId + origin + opBrowserState + salt) + '.' + salt;
}
function getOpBrowserState() {
var cookieName = 'opbs'; // The default cookie has a SameSite=None flag.
var fallbackCookieName = 'LEGACY_opbs'; // The legacy cookie has no SameSite flag. iOS12 treats SameSite=None incorrectly.
var cookie = getCookie(cookieName);
if (cookie === '' && cookieName !== fallbackCookieName) {
cookie = getCookie(fallbackCookieName);
}
if (cookie === '') {
return '';
}
var sid = CryptoJS.enc.Base64.parse(cookie);
return CryptoJS.enc.Utf8.stringify(sid);
}
function getCookie(name) {
var nameWithSeparator = name + '=';
var decodedCookie = decodeURIComponent(document.cookie);
var cookies = decodedCookie.split(';');
for (var i = 0; i < cookies.length; i++) {
var cookie = cookies[i];
while (cookie.charAt(0) === ' ') {
cookie = cookie.substring(1);
}
if (cookie.indexOf(nameWithSeparator) === 0) {
return cookie.substring(nameWithSeparator.length);
}
}
return '';
}
/*]]>*/
</script>
</head>
<body></body>
</html>
End session API
Endpoint: GET /oauth/v1/logout?post_logout_redirect_uri=https://postlogout.example.com&id_token_hint=eyJraWQiOiJmNDYzYmYyYy04MWE2LTQ5Nzk
Parameters
| Parameter | Required | Description |
|---|---|---|
id_token_hint |
Recommended | The previously issued ID token that was passed to the logout endpoint as a hint about the user's current authenticated session with the client |
post_logout_redirect_uri |
Optional | The URL to which the RP is requesting that the user agent be redirected after a logout is performed |
state |
Optional | Opaque value used by the RP to maintain the state between the logout request and the callback to the endpoint specified by the post_logout_redirect_uri query parameter |
The post_logout_redirect_uri must have been previously configured on the client. It is only respected if the id_token_hint is valid, it contains a valid client so the configuration can be retrieved, and the URI matches the configured default or additional post-logout redirect URIs.
If no post_logout_redirect_uri is provided as a parameter, the default value in the client configuration is used. If there is no configured URIs, it leaves the user on a success page.
For more details about the parameters, refer to the RP Initiated Logout.
Example response with a valid post-logout URI
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Successfully logged out</title>
</head>
<body>
<h1>Successfully logged out</h1>
<script>
window.onload = function () {
window.location.href = 'yourpostLogoutRedirectUri';
}
</script>
</body>
</html>
Front-channel logout support
The OneWelcome Identity Platform OP implementation also supports OpenID Connect Front-Channel Logout 1.0.
Front-channel with two RPs in the session
Example response
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Successfully logged out</title>
</head>
<body>
<h1>Successfully logged out</h1>
<iframe style="display:block; visibility:hidden" src="https://rp1logouturl.example.com"></iframe>
<iframe style="display:block; visibility:hidden" src="https://rp2logouturl.example.com"></iframe>
<script>
window.onload = function () {
window.location.href = 'yourpostLogoutRedirectUri';
}
</script>
</body>
</html>
