Rationale
The purpose of distributed Single sign-on and Single sign-out is automatically sign-in and sign-out to multiple different external services (herein: SSO target) when user signs in to onePortal via user-interface or OpenID Connect. For example, when user signs in to https://oneportal.t5.fi he/she will also be signed in to https://service1.example ja https://service2.example.com. Every namespace in onePortal can have multiple different external SSO targets and sign-on to these targets is completely transparent to user.
Mechanisms
Currently, onePortal provides two different mechanisms for Single sign-on: Management API (REST) and OpenID Connect. It is recommended to choose OpenID Connect when possible. Management API mechanism can be used when the SSO target already uses onePortal Management API for other purposes and already has required API credentials. In this case, it is simply less of a development burden to implement SSO via Management API.
Please note that SSO mechanisms are independent of the sign-in procedure being used. For example, if user signs in to onePortal via OpenID Connect, he/she can be automatically sign in to every SSO target regardless if those targets use Manangement API or OpenID connect mechanism. SSO mechanism defines the mechanism between the SSO target and onePortal server which is different/independent from the procedure between the user's browser and onePortal server.
Description of functionality
Single sign-on procedure is executed when user signs in to onePortal via user-interface or OpenID Connect. In both cases, user's browser will receive HTML <img> elements that contain src= attribute with an URL that points to the SSO target callback URL (meaning that the SSO requests originate from user's browser, not from onePortal server). Query parameters sso-token and sso-validity will be automatically added to this URL.. The SSO target can then use the token to fetch related user information from onePortal using either Management API or OpenID Connect, depending on the defined mechanism for the target. Parameter sso-token is a unique token that can only be used by the SSO target that it was assigned to. Ie. tokens can not be shared between different targets but each target will be given its own token. Tokens can be used only once as they are deleted immediately after being consumed. Parameter sso-validity defines the token validity time in minutes, after this validity period, the token will be permanently removed and can not be consumed anymore by the SSO target.
It is the responsibility of the SSO target to store the user information retrieved using the token. The SSO target should also send a cookie to the user's browser so it can later identify which token belonged to which user. Cookie validity time does not need to be the same as the token validity time but can be freely chosen by the SSO target. It is recommended to store the token and validity time to an http session and send a response to the user's browser immediately to make sure that the SSO procedure completes as fast as possible and the browser receives the cookie before it is redirected to another page (as is the case when user signs in via OpenID Connect). Token should only be consumed after the user first time enters the service or shortly before the token expires if it is desirable to sign-in the user regardless of whether he/she actually enters the service (for later identification purposes, ie. token might expire in 3 days but the user might first enter the service after 7 days).
The HTTP response (in addition to the cookie) from the SSO target should contain a valid image of the type jpg, png or ico (16x16 pixels in size). This image may be shown on user's browser, depending on the settings.
Single sign-out
Single sign-out procedure is executed when user signs out from onePortal via user-interface or OpenID Connect. In both cases, user's browser will receive HTML <img> elements that contain src= attribute with an URL that points to the SSO target sign-out URL (meaning that the SSO requests originate from user's browser, not from onePortal server). When SSO target receives this sign-out request, it should immediately invalidate user's session or, at least, remove any user-related information from session. These <img> tags are generated only for SSO targets that have consumed their token as there is no need to sign out from target that has not consumed the token because the user is not signed in to that service. All tokens, consumed or not, for current session will also be removed from database on Single sign-out which means that they can not be consumed afterwards.