Skip to main content

OpenID Connect (OIDC) overview

Guidance for people wanting to use the NHS CIS2 Authentication and OpenID Connect 1.0 to verify the identity of users and obtain basic profile information.

Page contents

Introduction

OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol.

It allows Clients to verify the identity of an End-User based on the authentication performed by an authorisation server, as well as to obtain basic profile information about the End-User in an interoperable and REST-like manner.

The full set of specifications describing OpenID Connect can be found at http://openid.net/connect/ and details of the NHS CIS2 Authentication support for the specifications can be found in the detailed guidance.

Actors

The following actors take part in an OpenID Connect authentication:

Actor Description
OpenID Provider (OP) An OAuth 2.0 Authorisation Server that is capable of authenticating an End-User and providing information to a Relying Party about the authentication event and the End-User.
Relying Party (RP) The client application requesting End-User authentication and information about the End-User.
End-User  The human participant being authenticated and about whom the Relying Party is requesting information.

Key terms

The following key terms are commonly used:

Key term Description
Claim A piece of information asserted about an entity. OpenID Connect defines a number of standard claims e.g. the name claim represents an End-User’s full name in displayable format.
Scope A collection of claims. OpenID Connect defines a number of standard scopes that a Relying Party can request about an authentication event or End-User. For example the profile scope contains claims such as: name, family_name, given_name etc.
ID Token     A JSON Web Token (JWT) that contains claims about the authentication event and may contain claims about the End-User. An ID Token is requested using the openid scope.
Access Token     A credential used to access protected resources. Access tokens represent specific scopes and duration of access.
Refresh Token A credential used to obtain access tokens. Refresh tokens are issued to the client by an authorization server and are used to obtain a new access token when the current access token becomes invalid or expires.
UserInfo Endpoint A protected resource that, when presented with an access token returns information about an End-User.

Authorization Code Flow

OpenID Connect defines three types of authentication flow to cater for different client types: the Authorization Code Flow, the Implicit Flow and the Hybrid Flow. The Authorization Code Flow is the most commonly used flow and is designed for use with web applications. It is the only flow currently supported by NHS CIS2 Authentication.

The diagram below depicts the Authorization Code Flow at a high level:

OpenID Connect Authorization Code Flow

  1. The Relying Party sends a request to the OpenID Provider to authenticate the End-User. The request must include the Relying Party’s identity and the openid scope, it may optionally include other scopes e.g. the email scope if the Relying Party wishes to obtain the user’s email address.
  2. The OpenID Provider authenticates the End-User using one of the methods available to it and obtains authorization from the End-user to provide the requested scopes to the identified Relying Party.
  3. Once the End-User has been authenticated and has authorized the request the OpenID Provider will return an Authorization Code to the Relying Party’s server component.
  4. The Relying Party’s server component contacts the token endpoint and exchanges the Authorization Code for an ID Token identifying the End-User and optionally Access and Refresh Tokens granting access to the Userinfo endpoint.
  5. Optionally the Relying Party may request the additional user information (e.g. email address) from the UserInfo endpoint by presenting the Access Token obtained in the previous step.

This flow provides the dual benefits of:

  1. Not exposing any tokens to the user agent or applications with access to the user agent.
  2. Allowing the Relying Party to be authenticated before exchanging the Authorization Code for tokens.

This flow requires that a Relying Party can securely maintain a client secret between themselves and the OpenID Provider.

Data Artefacts

This section describes at a high level the data artefacts used in the flow above.

Authorization Code

The Authorization Code is a temporary code generated by the OpenID Provider. An Authorization Code can only be used once and typically has a short expiry time. The structure of the Authorization Code is opaque to the client.

Example Authorization Code

code=zfg9bQACfe743lKypr9x3ovVC6s

ID Token

The id token is a JSON Web Token (JWT) that contains claims about the authentication of an End-User and their identity. The claims are represented in a simple JSON object.

Example ID Token

{
 "iss": "https://server.example.com",
 "sub": "24400320",
 "aud": "s6BhdRkqt3",
 "nonce": "n-0S6_WzA2Mj",
 "exp": 1311281970,
 "iat": 1311280970,
 "auth_time": 1311280969,
 "acr": "urn:mace:incommon:iap:silver"
}

The JSON object is signed using a JSON Web Signature (JWS). Signing the token allows the integrity and origin of the token to be validated by the Relying Party.

Finally the id token header, JSON claims and signature are encoded into Base64URL strings separated by a . character.

Example ID Token Header

"eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ.ewogImlzcyI6ICJodHRwOi8vc2VydmVyLmV4W1wbGUuY29tIiwKICJzdWIiOiAiMjQ4Mjg5NzYxMDAxIiwKICJhdWQiOiAiczZCaGRSa3F0MyIsCiAibm9uY2UiOiAibi0wUzZfV3pBMk1qIiwKICJleHAiOiAxMzExMjgxOTcwLAogImlhdCI6IDEzMTEyODA5NzAKfQ.ggW8hZ1EuVLuxNuuIJKX_V8a_OMXzR0EHR9R6jgdqrOOF4daGU96Sr_P6qJp6IcmD3HP99Obi1PRs-cwh3LO-p146waJ8IhehcwL7F09JdijmBqkvPeB2T9CJNqeGpegccMg4vfKjkM8FcGvnzZUN4_KSP0aAp1OJ1zZwgjxqGByKHiOtX7TpdQyHE5lcMiKPXfEIQILVq0pc_E2DzL7emopWoaoZTF_m0_N0YzFC6g6EJbOEoRoSK5hoDalrcvRYLSrQAZZKflyuVCyixEoV9GfNQC3_osjzw2PAithfubEEBLuVVk4XUVrWOLrLl0nx7RkKU8NXNHq-rvKMzqg"

Access Token

An access token is a credential used to access protected resources. It represents specific scopes and durations of access, granted by the resource owner, and enforced by the resource server and authorization.

OAuth 2.0 supports a number of access token types. The type used by OpenID Connect are bearer tokens which can be simply understood as meaning “give access to the bearer of this token”. Access tokens can have different formats, structures, and methods of utilization based on the resource server security requirements. However they are represented as a string the structure of which is opaque to the client.

An example of a returned access token is given below:

Example Access Token

access_token=jHkWEdUXMU1BwAsC4vtUsZwnNvTIxEl0z9K3vx5KF0Y

Refresh Token

A refresh token is a credential used to obtain access tokens.

Refresh tokens are issued to the client by the authorization server and are used to obtain a new access token when the current one becomes invalid or expires, or to obtain additional access tokens with identical or narrower scope.

Unlike access tokens, refresh tokens are intended for use only with authorization servers and are never sent to resource servers. As for access tokens a refresh token is represented as a string that is opaque to the client.

Example Refresh Token

refresh_token=9yNOxJtZa5

UserInfo

As described above the id token principally holds claims about the authentication event and the identity of the End-User.

A Relying Party wishing to obtain further data about the End-User can do this by presenting the access token they obtained to the userinfo endpoint. A successful request will result in a JSON object containing claims about the End-User being returned.  

An example JSON object is given below:

Example UserInfo

{
   "sub": "248289761001",
   "name": "Jane Doe",
   "given_name": "Jane",
   "family_name": "Doe",
   "email": "[email protected]",
  }

Last edited: 18 June 2024 10:19 am