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

Overview

This article shows a basic example with two different sites that use SSO during authentication. It provides an understanding of the general process of 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 an OpenID Connect authorization request
3. The identity server (in this article we used the Curity Identity Server) authenticates the user
4. The identity server establishes an SSO session
5. The identity server 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 an OpenID Connect authorization request
3. The identity server finds the existing SSO session and uses it
4. The identity server sends a new ID token
5. Site B validates and uses the token to setup a local session

Web Sessions vs. SSO Sessions

Web sessions and SSO sessions 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 is managed by the identity server.

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

The Role of the Identity Server

In this scenario, the identity server acts as the single point of trust for authentication, often called an Identity Provider(IdP). It handles the login and creates sessions.

The identity server uses different authentication methods to verify the user's identity. Once it verifies the identity, the server sets up a session for the authenticated user.

If a returning user (browser) can be matched against an existing 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 identity server, each authenticator has an identifier - an Authentication Context Class Reference, or ACR.

The ACR can have a form of URN; for example, it could look something like this:

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

If the client requests one or many ACRs for authentication, the server will enforce that the user is authenticated using one of those, that is, the server will only reuse sessions that were established with at least one of the requested ACRs. If there is no such session, the server will try to authenticate the user with the requested authentication method.

SSO Requirements

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

• Sites must be able to use the same authentication methods (identified by the same ACRs)
• SSO session must exist
• SSO session is fresh
• No client prompts

Shared ACRs

SSO only occurs if two applications have the same ACR in their requests and configuration. For example, if the user logs in with a username and password on 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 sound like pointing out the obvious, but there is a bit more to it, since the SSO session must also match the parameters provided in the client request.

SSO Session Should be Fresh Enough

The duration of the session is normally configured in the identity server, but the client can also specify in the request a desired freshness using the max_age parameter. The identity server will reuse the SSO session if it is not older than the requested parameter; otherwise, the user will have to authenticate.

Avoiding SSO

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

The Role of the Client

The clients (in our example, each site) send the requests for authorization and provide the identity server with the parameters and required information. Afterwards, they make 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.

These parameters are optional in OpenID Connect. They allow the client to specify and modify the configured authentication behavior. You can think of them as instructions for the identity server.

The Identity Server's Response

The OpenID Connect response from the server includes an id_token that the site uses when it sets up its authenticated session.

Validating the ID Token

Clients must validate the ID token before they use it. Read more about ID token validation here: Validating an ID Token.

Using the ID Token

Once the ID token has been validated, you can use the provided claims on your site.

OAuth vs OpenID Connect and SSO

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

Last updated: 2025-01-23

Jacob Ideskog

Identity Specialist and CTO at Curity