3. 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. This section is intended to provide a detailed guide to the flow as provided by NHS CIS2 Authentication OpenID Provider.

Should a Relying Party have a need to use a different client type they should contact [email protected] to discuss whether its use can be enabled.

The diagram below illustrates a typical use of the Authorization Code Flow.

1. An Authorization Code Flow is typically initiated when the Relying Party's web application receives a request for a web page by an End-User for whom no session has been established.
2. In response the Relying Party creates an Authentication Request and returns a redirect to the End-User's browser causing the request to be directed to the Authorization Endpoint. The request will contain a list of the scopes of interest to the Relying Party and a Redirection URI to which the response should be returned.
3. 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. The authentication may result in multiple flows between the OpenID Provider and End-User's browser. End-User consent to share the requested scopes is implied as a result of having signed the Terms and Conditions of Use for NHS CIS2 Authentication.
4. Once the End-User has been authenticated the OpenID Provider returns an Authorization Code to the Relying Party's web application using a redirect via the End-User's browser to the Redirection URI specified in the original request.
5. The Relying Party’s web application presents its Client Credentials to the Token Endpoint and exchanges the Authorization Code for an ID Token identifying the End-User and Access and Refresh Tokens granting access to the UserInfo endpoint.
6. The Relying Party's web application presents the Access Token obtained to the UserInfo Endpoint to obtain the user information requested via the scopes included in the original request.
7. The Relying Party's web application serves the web page requested by the End-User.

Request

When a Relying Party requires that an End-User is authenticated they should cause a HTTP GET request to be sent from the End-User’s user agent to the OpenID Provider’s Authorization Endpoint. Communication with the Authorization Endpoint must utilize TLS.

The request may be generated either:

• indirectly via a HTTP 302 redirect response, for example in response to a user attempting to access a protected resource) or
• directly, for example as a result of a login button being hit

 An example of each is given below:

The OpenID Connect Core Specification defines a number of mandatory and recommended parameters to use in the request. The minimum RECOMMENDED set is as follows:

The NHS CIS2 Authentication OpenID Provider supports the following optional parameters:

Should a Relying Party have a need to use an optional parameter not described above they should contact [email protected] to discuss whether its use can be enabled.

If the End-User is successfully authenticated the NHS CIS2 Authentication OpenID Provider will return an Authorization Code to the Relying Party’s web application component. This is achieved by returning a HTTP 302 redirect request to the End User’s user agent requesting that the response is redirected to the redirection_uri specified in the Authorize Request.

The response will contain a code parameter and state parameter. The client must ignore unrecognized response parameters.

The code parameter holds the Authorization Code which is a string value which is opaque to the Relying Party. It can be presented to the Token Endpoint to obtain ID, Access and Refresh Tokens. The code is valid for 120 seconds and can only be used once.

The state parameter will hold the state value provided in the original Authorize Request.

The Relying Party must implement CSRF protection for its redirection URI. This is typically accomplished by requiring any request sent to the redirection URI endpoint to include a value that binds the request to the user-agent's authenticated state (e.g. a hash of the session cookie used to authenticate the user-agent). The state parameter should be used for achieving this as described in the OAuth 2.0 Authorization Framework. Please see Security Considerations for more information

If the Authorization Request fails the NHS CIS2 Authentication OpenID Provider will return an error response to the Relying Party. As for a successful response this is achieved by returning a HTTP 302 redirect request to the End User’s user agent requesting that the response is redirected to the redirection_uri specified in the request.

The response will contain an error, error_description and state parameters. 

Most error codes result from an invalid request format e.g. a response_type other than code. However the following error may occur as the result of a valid request:

If the Client Identifier or Redirection URI specified is invalid an error will be returned directly to the user agent. Similarly HTTP errors unrelated to OpenID Connect will be returned to the user agent using the appropriate HTTP status code.

Failure of the End-User to authenticate successfully e.g. failure to enter valid credentials will result in a response not being returned to the Relying Party.

Request

Once the Relying Party web application has received an Authorization Code it can request the NHS CIS2 Authentication OpenID Provider to provide the associated ID, Access and Refresh tokens. It does this by sending a HTTP POST request over TLS directly to the Token Endpoint URI.

The following parameters must be sent using the "application/x-www-form-urlencoded" format with a character encoding of UTF-8 in the HTTP request entity-body:

As part of the registration process the Relying Party and the NHS CIS2 Authentication will have agreed a mechanism by which the Relying Party can be authenticated when making the token request. This is required to ensure that the request is genuine and that the tokens are not returned to a third party masquerading as the Relying Party.

Recommendation

NHS CIS2 Authentication recommend clients use private_key_jwt authentication, with the public key(s) hosted as a jwks endpoint, due to its increased security and ability to seamlessly roll over to a new keypair without requiring a configuration change. Clients may start with client_secret in the DEV Simple OIDC realm, but should use private_key_jwt in the Healthcare realms. 

Authentication Mechanisms

Authentication JWT

For both of the Private Key JWT and Client Secret JWT mechanisms the Relying Party must construct a JWT that must contain the following required Claim Values and may contain the following optional Claim Values:

The JWT may contain other Claims. Any Claims used that are not understood will be ignored.

The authentication token must be sent as the value of the client_assertion parameter.

The value of the client_assertion_type parameter must be "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"

Private Key JWT

For Private Key JWT authentication the JWT is signed using a private key owned by the Relying Party.

The example below shows the use of a JWT signed with a private key to authenticate (in this example the JWT value has been abbreviated).

The JWT is comprised of three Base64URL encoded elements separated by a . character. The first element is the token header. If we decode the value from the example above we get the JSON document object:

This specifies that the token has been signed with ECDSA utilising a P-256 curve and SHA-256 hash algorithm using the key identified by the string “16”.  Decoding the second element would give the JSON object containing the claims about the Relying Party e.g. the client identifier, expiration date etc.

The NHS CIS2 Authentication OpenID Provider advertises its supported signing algorithms via its OpenID Provider Configuration Document as described further in the Discovery section - for client authentication, these are listed in the "token_endpoint_auth_signing_alg_values_supported" value.

Further details on how the Relying Party is expected to use a JSON Web Key Set Endpoint to publish the details of the key associated with the kid are given in the Key Management section. 

Client Secret JWT

For Client Secret JWT authentication the JWT is signed using an HMAC SHA algorithm, such as HMAC SHA-256. The HMAC (Hash-based Message Authentication Code) is calculated using the octets of the UTF-8 representation of the client_secret as the shared key.

If the request validation is successful the NHS CIS2 Authentication OpenID Provider will return an HTTP 200 OK response including ID, Access and Refresh tokens as in the example below:

The response body will include the following parameters:

ID Token

The ID Token is a security token that contains Claims about the authentication of an End-User by an Authorization Server. The ID Token is represented as a JWT as described in the JSON Web Token Specification and is signed using JWS as described in the JSON Web Signature Specification. 

The ID Token is comprised of three Base64URL encoded elements separated by a . character. The first element is the JOSE (JSON Object Signing and Encryption) Header describing the signing algorithm used, the second element contains the Claims and the third the signature.

JWTs may be conveniently decoded for inspection using an online website such as https://jwt.io/.

If we decode the value from the example above we get the JOSE Header below:

This specifies that the token has been signed with an RSA Signature utilising the SHA-256 hashing algorithm and the key identified by the string “b/O6OvVv1+y+WgrH5Ui9WTioLt0=”. Details on how the Relying Party may obtain the public key associated with kid are given in the Key Management section.

Decoding the second element gives us the JSON object containing the Claims about the authentication of an End-User. For example:

The third element is the signature over the JSON object. Details on how this signature is created and on how to validate it can be found in the  JSON Web Signature Specification.

The ID Token contains the following Claims of interest.

Any Claims contained in the ID Token other than those listed in the table above MUST be ignored by the Relying Party.

Relying Parties must validate the ID Token in the Token Response in the following manner:

1. The the value of the iss Claim must exactly match the Issuer Identifier for the NHS CIS2 Authentication OpenID Provider as specified in the OpenID Provider Configuration Document.
2. The aud Claim must contain the Relying Party's Client identifier.
3. If the ID Token is received via direct communication between the Client and the Token Endpoint, then TLS server validation may be used to validate the issuer in place of checking the token signature (see the TLS Requirements section). The Client must validate the signature of all other ID Tokens according to  JSON Web Signature Specification using the algorithm specified in the JWT alg header parameter. The Client must use the keys provided by the NHS CIS2 Authentication OpenID Provider as described in the Key Management section. 
4. The current time must be before the time represented by the exp Claim.
5. If a nonce value was sent in the Authentication Request, a nonce Claim will be present and its value must be checked to verify that it is the same value as the one that was sent in the Authentication Request. The Relying Party should check the nonce value for replay attacks. 
6. If the acr Claim was requested, the Replying Party should check that the asserted Claim Value is appropriate. For further details on NHS CIS2 Authentication's support for acr values see the ACR and AMR Values section.
7. The Relying Party should check the auth_time Claim value and request re-authentication if it determines too much time has elapsed since the last End-User authentication. For further guidance see the Session Management section.

Relying Parties may validate the integrity of the Access Token using the value of the at_hash Claim. Its value is the base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the access_token value, where the hash algorithm used is the hash algorithm used in the alg parameter of the ID Token's JOSE Header. The alg value for the NHS CIS2 Authentication OpenID Provider is RS256 so to obtain the value hash the access_token value with SHA-256, then take the left-most 128 bits and base64url encode them.

If the Token Request is invalid or unauthorized an HTTP 400 response will be returned as in the following example:

The NHS CIS2 Authentication OpenID provider's ID Token only contains Claims about the authentication event and the identity of the End-User. Other information about the End-User can be requested by including additional Scopes in the authentication request (as in the example request above which includes the standard profile scope) and by presenting the Access Token from the Token Response to the UserInfo endpoint.

The Relying Party sends the UserInfo Request using either HTTP GET or HTTP POST. The Access Token obtained from an OpenID Connect Authentication Request must be sent as a Bearer Token.

It is recommended that the request use the HTTP GET method and the Access Token be sent using the Authorization header field as in the example below:

The userinfo claims will be returned in a HTTP 200 OK response as in the example below:

The userinfo claims will always include a sub Claim. This must be verified to exactly match the sub Claim in the ID Token; if they do not match, the UserInfo Response values must not be used.

The Relying Party should authenticate the OpenID Provider either by checking the TLS certificate (see the TLS Requirements section) or by validating the signature of the JWT if provided. For details on how to obtain a signed UserInfo Response see the next section.

More details of the Scopes and Claims that may be obtained via the UserInfo Endpoint can be found in the Scopes and Claims section.

During registration the Relying Party MAY request that the UserInfo Response is signed in which case the response will contain iss and aud claims. The Relying Party SHOULD validate that both the iss value matches the NHS CIS2 Authentication OpenID Provider’s Issuer Identifier and the aud claim matches the Relying Party's Client Identifier. 

The Relying Party SHOULD validate the signature according to the JSON Web Signature Specification.

When a request fails, the UserInfo resource server will respond using the appropriate HTTP status code (typically, 400, 401, 403, or 405) and include an error code in the response.

The response will contain an error parameter and an error_description.

It is anticipated that Relying Parties will only require access to the UserInfo Endpoint at the time of the original End-User authentication. This should only happen once as part of a Relying Party authentication journey and the Access Token can be used immediately, then discarded. In NHS CIS2 Authentication, there should be no other need to retrieve the User Info after this point in time. 

Therefore the use of the Refresh Token to obtain a new Access Token is not recommended.

Clients wanting to use the Refresh Token are requested to contact [email protected] to discuss their use case further.

In all environments, all of the CIS2 Authentication endpoints use dynamic IP addresses which may change on a regular basis. You MUST ensure any firewall rules or other security measures allow access via the domain name and the current set of IPs in use and do not rely on a static IP list.

CIS2 Authentication uses a content delivery network (CDN) in front of our endpoints which can cause issues if incorrectly configured proxies are used between an application and the CIS2 Authentication endpoints. Note that a proxy may legitimately be used to funnel requests over a private (HSCN) network or as a security boundary.

The CDN requires that the proxy supports both the HTTP host header and also SNI as part of the TLS handshake in order to correctly respond. Proxies solely relying on the IP address and not providing these values will see an error being returned.

An example NGINX configuration is as follows (please adjust to meet your requirements):

1. Registration
2. Discovery
3. Authorization code flow
4. Scopes and claims
5. ACR and AMR values
6. Signatures
7. Key management
8. Security considerations
9. Session management
10. Role selection