Skip to main content

Single Sign-On setup with OIDC client websites

This tutorial goes through a SSO setup process. This is intended for developers and administrators configuring external websites where they want users who are logged in at one site, to go to another site, and be visible already logged in without the need to click a “sign in” link at all. All such sites must already support normal OpenID Connect login process.

Pre-requirements​

You have multiple websites which already use normal OpenID Connect authorisation as user sign-in.

Goal​

You want to avoid users needing to click “sign in” when they arrive at a new site.

  1. User goes to site 1.

  2. User logs in at site 1.

  3. User goes to site 2 for the first time.

  4. User appears to already be signed in at site 2 without the need to interact with the UI.

How this works​

The goal is made possible by having the user’s browser make a request to site 2 during site 1’s authorisation process. During this request site 2 receives a token which it can use later to have the user sign in without interaction. Site 2 should set a cookie to the browser, which it will read later when the user arrives at site 2 for the first time. When this happens, site 2 redirects the user to the OpenID Connect authorisation URL with the token parameter included. If the token is valid, the user will authorise site 2 and is redirected back without interaction.

Step 1: Create a SSO callback endpoint​

Each site which wants to participate in this SSO scheme needs an endpoint which receives the token, adds browser cookies, and possibly returns an icon for display during authorisation.

The endpoint should be in the same domain as the site and other authorisation callbacks.

The endpoint should:

  • TODO Should the site always invalidate any previous user sessions, if such exist? TODO

  • Read added query parameters from the call

    • sso-token - The single-use SSO token

    • sso-validity - Token validity time in minutes from time of request, after which the token is invalidated if still unused.

  • Store the received information. Add cookies to the browser from the site’s own domain. The cookies should contain enough information to be able to use the above information later.

  • Optionally return a small logo image file in response, as this request came from an <img src=”callback-url” /> element.

Step 2: Provide the callback URL​

Go to the site’s client’s information in TIS, find the field “Single Sign-On Callback URL” and enter the callback endpoint’s URL here.

Step 3: Add a “Single Sign-On Target”​

Each “target” client will be sent their own SSO token, and each SSO token works only with that specific client.

In TIS management go to the “Single Sign-on” view.

Every site has a different OpenID Connect client registered. For each site:

  1. Click “Add”. Select “OpenID Connect” as the mechanism.

  2. Select the OpenID Connect client of the site.

  3. Configure other details if needed.

  4. Save the new Target.

Step 4: Use SSO token when un-signed-in user arrives​

When a new user arrives at site, and the site uses the browser cookies it added to detect that they have an SSO token available for use, the site should redirect the user to the authorisation URL with extra parameters:

  • sso_token={user's SSO token} - The user’s SSO token

  • prompt=none - No interactive UI is shown to user, sign-in fails if token is invalid and user is redirected to site’s failure URI.

If the token was valid, the authorisation goes through without confirmation and the user is redirected to the success callback without interaction.