Using OpenID Connect for a Single Sign-On Solution in Web Clients

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.

Overview of the SSO process

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

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

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 the Curity Identity Server, 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 the Curity Identity Server 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.

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.

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 the Curity Identity Server 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.