Overview

What is an OpenID Connect?

OpenID Connect is a standard published in 2014 that is built on top of the Oauth 2.0. It provides support for user authentication, and among others, allow the clients to obtain end-user identity attributes in an interoperable manner and manage multiple sessions. It is meant to be a lightweight, modern, JSON-based alternative for a SAML.

The OpenID Connect specification defines Relying Party (RP) as an OAuth 2.0 Client requiring End-User authentication, and OpenID Provider (OP) as an OAuth 2.0 Authentication Server which performs this authentication. As a result of successful authentication, the OpenID Provider issues an ID Token which is a JWT-compliant JSON object containing a set of claims - user identity attributes.

The Token Server acts as an OpenID Provider which manages the ID Tokens and authentication process. The Token Server, however, does not manage the identity management by itself, the actual authentication is delegated to an Identity Provider.

OpenID Connect flows

The OpenID Connect specification defines three main flows: the Authentication using the Authorization Code Flow, the Implicit Flow, and the Hybrid Flow.

Authorization Code Flow

The Authorization code flow is an extension of OAuth 2.0 authorization code flow. The client obtains the Authorization Code from authorization endpoint using a front-channel (ie via user agent such as web browser). This code can be then exchanged at token endpoint for an access token and/or ID token using the back-channel (e.g. client's backend server). This workflow is suitable for clients that can securely store the client secret which is required when exchanging the code for the token.

In order to obtain the ID Token in this flow, make sure the web client has the grant type Authorization Code enabled and create an OAuth authorization request with openid scope.

Implicit Flow

Implicit flow is a one step flow - the client requests an access token and/or ID Token directly from the authorization endpoint using a front-channel (ie via user agent such as web browser). This workflow is suitable for those clients that cannot store client secret in a secure fashion (e.g. web applications running inside user agent such as web browser).

In order to obtain the ID Token in this flow, make sure the web client has the grant type Implicit enabled and create an OAuth authorization request with response_type=id_token and openid scope.

Hybrid Flow

The Token Server currently does not support the Hybrid Flow.

OpenID Connect scopes

In order to issue an ID Token, the authorization request must contain at least the openid scope. It is possible to control which user claims are included in the ID token by specifying additional scopes.

The table below summarizes the scopes relevant for OpenID Connect.

scope Description
openid Activates the OpenID functionality and allows to issue ID Token as a part of OAuth 2.0 authorization request.
profile Requests access to the following claims: name, family_name, given_name, nickname, preferred_username, gender, birthdate, locale.
email Requests access to the following claims: email and email_verified.
address Requests access to address claim that is composed of the following fields: street_address, locality, region, postal_code, country
phone Requests access to the following claims: phone_number and phone_number_verified

The claims are obtained from the Identity Provider via Person API and mapped as listed below:

claim Person API source
name profile > name > first + last
given_name profile > name > first
family_name profile > name > last
nickname profile > name > display_name
preferred_username profile > name > display_name
gender profile > gender
birthdate profile > date_of_birth
locale profile > preferred_locale
email profile > email_addresses > value
email_verified profile > email_addresses > verified
phone profile > phone_numbers > value
phone_​number_​verified profile > phone_numbers > verified
address > street_address profile > address > street_name + house_number + house_number_addition
address > locality profile > address > city
address > region profile > address > region
address > postal_code profile > address > postal_code
address > country profile > address > country_name

Optional claims

ACR

Note: This feature requires the Onegini CIM

ACR (Authentication Context Class Reference) allows you to request that a specific authentication context be met upon successful authentication.

The table below summarizes currently supported values. The available values are also exposed via the Discovery API.

ACR value Description
urn:onegini.com:oidc:authentication_level:1 Requires an authentication level of at least 1 from Onegini CIM.
urn:onegini.com:oidc:authentication_level:2 Requires an authentication level of at least 2 from Onegini CIM.
urn:onegini.com:oidc:authentication_level:3 Requires an authentication level of at least 3 from Onegini CIM.
urn:onegini.com:oidc:authentication_level:4 Requires an authentication level of at least 4 from Onegini CIM.

To request a specific ACR value include acr_values parameter when requesting ID Token, e.g.:

http://tokenserver.example.com/oauth/authorize?response_type=code&client_id=openid&redirect_uri=http%3A%2F%2F.example.com&scope=openid&state=d5dbda85-ecdb-4172-9ada-7ba15c6982d0&acr_values=urn:onegini.com:oidc:authentication_level:2

Currently only a single ACR value can be specified at a time. Sending multiple values will result in a Bad Request error. The Onegini Token Server may return an ACR with a value that is higher than the authentication level that was requested.

Further reading:

Custom attributes

Note: This feature requires the Onegini CIM

The Onegini CIM supports custom attributes for a user. These attributes are included as claims within ID Token.

Discovery

The Onegini Token Server implements OpenID Connect Discovery which enables a Relying Party to determine the capabilities of the OpenID Provider at runtime. See Discovery API for the API reference.

UserInfo

The Onegini Token Server exposes claims via User Info endpoint. See User Info for the API reference.

Json Web Key Set

The Onegini Token Server exposes keys used for calculating the digital signature of the ID Token via the JWKS endpoint.

ID Token encryption (JSON Web Encryption)

The ID Token can be encrypted to hide sensitive claims. By default this feature is turned off. See ID Token encryption for more information.

Session management

The Onegini Token Server supports session management. See Session Management for more details.