Distributed Single Sign-On and Single Sign-Out
Rationale
Distributed Single sign-on (SSO) automatically signs a user in to one or more external
services (each called an SSO target) when they sign in to Trivore ID, whether through its
own user interface or through OpenID Connect. For example, when a user signs in to
https://{your-id-server}, they can also be signed in automatically to
https://service1.example.org and https://service2.example.com. A namespace can have
multiple SSO targets, and sign-on to all of them is transparent to the user.
Mechanisms
Trivore ID provides two mechanisms an SSO target can use to consume an SSO token: the Management API and OpenID Connect. OpenID Connect is recommended where possible; the Management API mechanism is a good fit when the SSO target already integrates with Trivore ID's Management API for other purposes and already holds API credentials, since it avoids adding a second integration method.
The SSO mechanism is independent of how the user actually signs in. A user who signs in via OpenID Connect can still be signed in automatically to SSO targets that consume their token through the Management API mechanism, and vice versa — the mechanism only governs how the SSO target itself talks to the Trivore ID server, not how the user's browser talks to it.
How it works
Single sign-on runs whenever a user signs in via the user interface or via OpenID Connect. In
both cases, the user's browser receives HTML <img> elements whose src attribute points to
each SSO target's callback URL — the requests originate from the user's browser, not from the
Trivore ID server — with sso-token and sso-validity query parameters automatically added.
sso-tokenis a single-use token unique to that SSO target; tokens are not shared between targets, and each is deleted immediately after being consumed.sso-validityis the token's validity time in minutes. Once it expires, the token is permanently removed and can no longer be consumed.
The SSO target uses its token to fetch the user's information from Trivore ID, via whichever mechanism (Management API or OpenID Connect) it was configured to use. It is responsible for storing that information and for setting a cookie in the user's browser so it can recognize the same user later. The cookie's validity does not need to match the token's validity — choose whatever lifetime suits the target. Store the token and its validity as soon as it is received (for example in the HTTP session) and respond to the browser immediately, so the SSO exchange completes before the browser is redirected onward. If you want to identify the user for a period longer than the token's own validity — for example, recognizing a returning user up to 7 days later even though the token itself is only valid for 3 days — consume the token as soon as it is received rather than waiting for the user's next visit.
The HTTP response from the SSO target (in addition to setting the cookie) should contain a valid 16x16 pixel image (jpg, png, or ico), which may be shown to the user depending on settings.
Single sign-out
Single sign-out runs the same way, when a user signs out via the user interface or via OpenID
Connect: the browser receives <img> elements pointing at each SSO target's sign-out URL. A
target that receives this request should immediately invalidate the user's session, or at
least remove user-related information from it. These sign-out requests are only sent to
targets that had actually consumed their token — there is nothing to sign out of otherwise.
All tokens for the session, consumed or not, are also removed from the database on sign-out, so
none of them can be consumed afterward.
In this section
| Page | Description |
|---|---|
| OpenID Connect mechanism | How an SSO target consumes an sso-token via OpenID Connect, with a step-by-step tutorial |
| Management API mechanism | How an SSO target consumes an sso-token via the Management API |
| Creating SSO targets | Configuring SSO targets in the Management UI |
| Example source code | Reference implementations for both mechanisms |