Web Client SSO with OpenID Connect

Web Client SSO with OpenID Connect

develop

Using OpenID Connect for a Single Sign-On solution

Overview

In this article we discuss a basic example where we have two different sites that we want to have SSO between using the Curity Identity Server, with the goal of providing an understanding of the general process when implementing a web client.

If you haven't read the overview

Read more about the architectural overview of sso here


Overview of the SSO process

The basic SSO process, stripped of most details, is fairly simple:

overview

SITE A

  1. The user wants to login on Site A
  2. Site A sends a OpenID Connect Authorization Request
  3. Curity authenticates the user
  4. Curity establishes a SSO session
  5. Curity responds with an ID token
  6. Site A validates and uses the ID token to setup a local session

SITE B

  1. The user accesses Site B
  2. Site B sends a OpenID Connect Authorization Request
  3. Curity finds and uses the existing SSO session
  4. Curity sends a new ID token
  5. Site B validates and uses the token to setup a local session

Note

There are a number of different variants of the OpenID Connect protocol that can be used for this flow. The diagram shows a simplified flow.

About sessions

Please note that the web session and the SSO Session are different things. The web session is entirely on the client side and has to do with requests, responses and cookies that have nothing to do with the authentication or SSO. The SSO session is the authentication session, and lives its own life on the authentication service side.

If you want to learn more about the different sessions see Sessions and SSO.

What the server does

In this scenario, the identity server acts as the single point of trust authentication service, often called an IdP: Identity Provider : Identity Provider. It handles the login and creates sessions, by using a configured authentication profile.

In Curity, the server provides the logic for determining what Authenticators should be presented to a user, collecting the credentials required to verify the user identity.

If a returning user (browser) can be matched against an existing login session, that session will be used, if that session is fresh enough, and matches the requirements provided in the request.

ACR - Authentication Context Class Reference

In Curity, validation of credentials is done through Authenticators, which are part of an Authentication Profile. Each authenticator has an identifier, an Authentication Context Class Reference, or ACR.

The ACR is used as identifier for the authentication method, and can be manually configured in Curity. If not, authenticators are given a system defined ACR on this format:

urn:se:curity:authentication:${AUTHENTICATOR TYPE}:${AUTHENTICATOR ID}

Example:

urn:se:curity:authentication:html-form:html1

This means an authenticator of type html-form with the id html1.

Matching ACRs

If the client requests one or many ACRs for authentication the server will enforce that the user is authenticated using one of those. If not the server will pick an authenticator, or show a list of authenticators for the user, that matches what is configured for the requesting Client.

SSO Requirements

In order for SSO to be established, there are a few requirements:

  • Sites must share ACR:s (Authenticators)
  • SSO session must exist
  • SSO session is fresh
  • No client prompts

Shared ACRs

In order for SSO to work, the sites must have the same ACR in their requests and configuration. So for example if the user logs in with html-form in the first site, and the second site requires a social login, SSO will not occur.

SSO session must exist

There must exist an authenticated session (SSO session) for SSO to work. This might perhaps sound like pointing out the obvious, but there is a bit more to it, since the SSO session also must match the parameters provided in the client request.

SSO session is fresh

The duration of the session is normally configured in the authentication profile (by authenticator) in Curity, but the client can also specify in the request a desired freshness using the max_age parameter, and thereby implicitly request a new login, if the available SSO session is too old.

No client prompts

The client may prompt for authentication, in which case SSO will not be allowed - the client explicitly asked for the user to login again.

What the clients do

The clients (in our example, each site) sends the requests for authorization and provides Curity with the parameters and required information, and then makes use of the returned ID token.

The Request Parameters for SSO

A few of the request parameters specifically affect SSO; acr_values, max_age and prompt.

They are optional, but by passing these parameters, the client can specify authentication and modify the configured authentication behavior. You can think of them as instructions for the authentication service.

ParameterDescriptionCommentExample
acr_valuesGoverns the allowed authentication method for SSO.Requests that Curity uses a certain authenticator (or group of authenticators). Multiple strings are separated with space.acr_values=urn:se:curity:authentication:html-form:html1
max_ageSpecifies a maximum allowed age for the SSO session (in seconds)If the session is older, the user is prompted to login again.max_age=300
promptLets the authentication server know that login should be required.Allows for the client to force new authentication.prompt=login

The Curity Response

The OpenID Connect response from the server includes an id_token that is to be used when the site setup its authenticated session.

auth_time

The auth_time claim is useful to verify a recent authentication, since it shows the time of the last user login.

Validating the token

Before the ID Token is of any use, it must be validated. Read more about ID Token validation here: Validating an ID Token.

Using the token

Once the ID Token has been validated, you can use the provided claims in your site.

OAuth vs OpenID Connect and SSO

The request parameters listed above are OpenID Connect parameters, to be used with OpenID flows. But Curity allows client's to request the same parameters even for OAuth flows. However, the ID Token is only issued for OpenID Connect, so it is not possible for the client to verify that the authentication happened as expected when not using OpenID Connect.

Was this page helpful?