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.
OpenId Connect specification defines Relying Party (RP) that is an OAuth 2.0 Client requiring End-User authentication, and OpenID Provider (OP) that is an OAuth 2.0 Authentication Server which performs this authentication. As a result of successful authentication OpenID Provider issues an ID Token which is a JWT-compliant JSON containing a set of claims - user identity attributes.
The Token Server, being an implementation of an OpenID Provider, manages the ID Tokens and authentication process. However, since the Token Server does not manage the identity management by itself, the actual authentication is delegated to an Identity Provider.
OpenID Connect flows
OpenId Connect specification defines three main flows: Authentication using the Authorization Code Flow, Implicit Flow and Hybrid Flow.
Authorization Code Flow
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 access token and/or ID token using back-channel (e.g. client's backend server). This workflow is suitable for clients that can securely store client secret which is required when exchanging the code for the token.
In order to obtain ID Token in this flow make sure the web client has Authorization Code
enabled in Grant types
field 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 ID Token in this flow make sure the web client has Implicit
enabled in Grant types
field and create an OAuth authorization
request with response_type=id_token
and openid
scope.
Hybrid Flow
The Token Server currently does not support Hybrid Flow.
OpenId Connect scopes
In order to issue an ID Token, the authorization request must contain at least openid
scope. It is possible to control which user claims are included into 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 . |
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 |
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 |
Additional functionality
Discovery
The Token Server implements OpenID Connect Discovery which enables Relying Party to determine the capabilities of the OpenID Provider in the runtime. See Well-known API for the API reference.
UserInfo
The Token Server exposes claims via User Info endpoint. See User Info for the API reference.
Json Web Key Set
The Token Server exposes keys used for calculating digital signature of the ID Token via JWKS endpoint. See JKWS for the API reference.