On this page

1 Introduction

1.1 Purpose of document

NHS login platform implements OpenID Connect 1.0 OpenID Provider role to assert the identity of the End-User to a Partner Service, as well as enabling the Service to obtain basic profile information about the End-User in an interoperable manner.

This document defines the interfaces implemented by the platform and describes the data flows supported by these interfaces.

1.2 Audience

The primary audiences for this document are:

NHS login programme team

NHS Digital – Digital Delivery Centre

NHS Digital – other delivery teams

NHS England

3rd party suppliers integrating with the NHS login platform

1.3 Definitions

Where used in this document set, the keywords MUST, SHOULD and MAY are to be interpreted as follows:

MUST: This word, or the terms “REQUIRED” or “SHALL“, means that the definition is an absolute` requirement of the specification.

SHOULD: This word, or the adjective “RECOMMENDED“, means that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications MUST be understood and carefully weighed before choosing a different course.

MAY: This word, or the adjective “OPTIONAL”, means that an item is truly optional. One implementer may choose to include the item because a particular implementation requires it or because the implementer feels that it enhances the implementation while another implementer may omit the same item. An implementation which does not include a particular option MUST be prepared to interoperate with another implementation which does include the option, though perhaps with reduced functionality. In the same vein an implementation which does include a particular option MUST be prepared to interoperate with another implementation which does not include the option (except, of course, for the feature the option provides).

2 Specification Status

2.1 Scope / Constraints

This document relates to NHS login ‘Federation interface during beta phase. Further amendments WILL be implemented prior to full rollout – this document is a draft representing intended design, but is subject to clarification.

The NHS login platform supports authentication using the Authorization Code Flow only

Implicit & Hybrid Flows are not supported

HTTP is not supported – all HTTP-based flows must be HTTPs (using TLS v1.2 or above)

2.2 Changes in this version

Version 1.4e of this specification includes the following changes:
– Removal of environment section – environment details will be provided to Partners during the NHS login onboarding process
– Rationalise scope and claim names
– Specify Client Authentication for token endpoint
– Endpoints overview section
– Inclusion of asserted login identity optional parameter in Authentication Request
– Inclusion of reason_for_request, requesting_patient and requesting_system claims in access token to align with Spine Core JWT attributes
– Removed support for Public clients due to risk of masquerading & lack of identified need
– Updated signing algorithm to be RS512 (from RS256)

3.1 Authorization Code Flow

The Authorization Code Flow returns an Authorization Code to the client, which can then exchange it for an ID Token and an Access Token directly. This avoids exposing any tokens to the User Agent and possibly other malicious applications with access to the user agent.

Using this flow also means the Platform can also authenticate the Client before exchanging the Authorization Code for an Access Token. The Authorization Code flow is suitable for Clients that can securely maintain a Client Secret between themselves and the Platform.

The client sends the request to the Platform – via the User Agent (browser)

The Platform validates the Authentication Request

The Platform authenticates the End-User

The Platform obtains End-User Consent/Authorization

The Platform sends the Authorization Code to the Client via the End-User’s browser

The client requests a response using the Authorization Code at the Token Endpoint

The client receives a response that contains an ID Token and Access Token in the response body

The client validates the ID token and retrieves the End-User’s Subject Identifier.

3.2 Public and Confidential Clients

Clients are classified as either Public or Confidential based on their ability to maintain the confidentiality of their credentials.

3.2.1 Confidential Client

The client is capable of maintaining the confidentiality of its credentials. For example, the client is implemented on a secure server with restricted access to its credentials.

3.2.2 Public Client

This section is provided for information only; public clients will not be supported in NHS login Public Beta phase.
A Public client is incapable of maintaining the confidentiality of its credentials. For example, the client executes on a device used by the end user, such as an installed native application or browser-based application.

Public clients using the Authorization Code flow are susceptible to authorization code interception attacks. For example, a rogue application could intercept the authorization code as it is being passed through the mobile/native operating system. To mitigate this attack, public clients must follow the Proof Key for Code Exchange (PKCE) specification, which binds the Authorisation Request to the subsequent Token Request. PKCE is an extension to the regular Authorization Code flow, so the flow is the same, except that PKCE elements are included at various steps.

Public clients are also at risk of masquerading by malicious services; a malicious service could re-use the client_id of a genuine Public client and trick a user into revealing their information.

For the above reasons Public clients will not be supported in NHS login Public Beta phase.

3.3 Endpoints

/.well-known/openid-configuration – This is the standard openid discovery address – this will maintain full addresses for the below endpoints. This is consumed by a Service with a direct HTTPs call.
/.well-known/jwks.json – The Keys used by NHS login to sign tokens are available here. This is consumed by a secure Service’s backend with a direct HTTPs call.
/authorize – This initiates the Authorization Code flow – the endpoint is consumed by directing a user-agent (typically a web browser) to the endpoint address, using HTTPs. This is also termed the OIDC Authentication Endpoint.
/token – This is used to retrieve tokens, including ID tokens, by exchanging an authorization code. This is consumed by a secure Service’s backend with a direct HTTPs call.
/userinfo – This endpoint is used after retrieving tokens – sensitive and/or time-bound attributes are available from this endpoint. This is consumed by a secure Service’s backend with a direct HTTPs call.

3.4 Authorize Endpoint

3.4.1 Authentication Request

References:

OpenID connect core specification [1], section 3.1.2.1

International government assurance profile (iGov) for OpenID Connect [2]

The client initiates an authentication request to the NHS Digital NHS login authorize endpoint using the HTTP GET or POST methods. If using HTTP GET, then the parameters are serialised using URI query serialisation. In the case of HTTP POST, then the parameters are serialised using form serialisation

Authentication request parameters are:

Table 1: Authentication request parameters

Parameter

Req?

Value(s)

Description

scope

Mand

“openid”

The openid scope value MUST be present.

Other scope values listed MAY be present. Scope values used that are not understood by NHS login WILL be ignored.

OAuth 2.0 response type value that determines the authorization processing flow to be used, including what parameters are returned from the endpoints used. When using the Authorization Code Flow, this value MUST be “code”

client_id

Mand

OAuth 2.0 Client Identifier
This is a static identifier previously provided by the NHS login Partner Onboarding team

redirect_uri

Mand

Redirection URI to which the response will be sent. This URI MUST exactly match one of the Redirection URI values for the Client pre-registered at the OpenID Provider

When using this flow, the Redirection URI MUST NOT use the http scheme

The redirection URI MAY use an alternate scheme, such as one that is intended to identify a callback into a native application

State

Mand

Opaque value used to maintain state between the request and the callback. Typically, Cross-Site Request Forgery (CSRF, XSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie

This value will be returned to the client in the authentication response

The iGov profile for OIDC specifies this parameter as Mandatory to help RPs protect against CSRF attacks.

response_mode

n/a

The only response_mode supported NHS login will be the default mode (“query”), where the Authorization Response parameters are encoded in the query string which is added to the redirect_uri when redirecting back to the Client

See OAuth 2.0 Multiple Response Type Encoding Practices [4]

Nonce

Mand

String value used to associate a Client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authentication Request to the ID Token. Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values

The iGov profile for OIDC specifies this parameter as Mandatory to help RPs protect against CSRF attacks.

display

Opt

“page”

“touch”

ASCII string value that specifies how the Platform displays the authentication and consent user interface pages to the End-User. The defined values shown “page” and “touch” are supported for NHS login beta phases, with the default value being “page”.

“popup” and “wap” values are not supported

prompt

Opt

<blank>

“none”

“login”

Requests that the NHS login service forces the user to sign-in, or to request that the service does not prompt the user to sign-in (SSO)

<blank> – The Service will SSO the user if they still have a valid session, else the user will be requested to login

none – The Service will SSO the user if they still have a valid session, otherwise an error code is returned

login – The Service will request the user to login, regardless of a session already existing

The purpose of this parameter is to support seamless (or “single”) login between two RPs (RP1 and RP2) where cookie-based SSO is not available. The content will be a signed jwt with payload containing “code” attribute with the value being an Authorization Code issued to RP1. The jwt “iss” attribute MUST contain the client_id of RP1, have an “exp” of no longer that 60 seconds and MUST be signed by RP1 using its client private key. RP1 passes the jwt to RP2 for RP2 to use in its authentication request.

3.4.1.1 Scope to be requested

References:
• OpenID Connect Core Specification [1], section 5.1

Scopes can be used to request that specific sets of information be made available as Claim Values when making an Authentication Request.

3.4.2 Authentication Request Validation

The Authentication Request is authenticated as described in OpenID Connect Core Specification [1], s3.1.2.2

Additional validations are:

the submitted redirect URI is an exact match of the one of the redirection URI values registered for the client

3.4.3 Authorisation Server Authenticates the End-User

Outside the scope of this spec

3.4.4 Authorisation Server obtains End-User Consent / Authorisation

Outside the scope of this spec

3.4.5 Authentication Response

3.4.5.1 Successful response

References:

OpenID Connect Core Specification [1]

RFC6749 – the OAuth 2.0 Authorization Framework [6]

The Authentication Response returns the parameters listed in Table 3 by adding them as query parameters to the redirect uri specified in the Authentication Request.

Table 3: Authentication Successful Response

Parameter

Req?

Description

Code

Mand

The authorization code generated by the NHS Login Platform.

The authorization code MUST expire shortly after it is issued to mitigate the risk of leaks. A maximum authorization code lifetime of 10 minutes is RECOMMENDED.

The client MUST NOT use the authorization code more than once. If an authorization code is used more than once, the Platform MUST deny the request and SHOULD revoke (when possible) all tokens previously issued based on that authorization code.

The authorization code is bound to the client identifier and redirection URI

State

Mand

if the “state” parameter was present in the client authorization request, then it MUST be the exact value received from the client, otherwise not included

3.4.5.2 Error Response

References:

OpenID Connect Core Specification [1]

RFC6749 – The OAuth 2.0 Authorization Framework [5],
s4.1.2.1

If the authentication request is denied or fails, the authorisation server informs the client using the parameters defined in Table 4. Unless the Redirection URI is invalid, the Authorisation Server returns the client to the Redirection URI specified in the Authentication Request with the error and state parameters. Other parameters should not be returned

Table 4: Authentication Error Response

Parameter

Req?

Description

error

Mand

Error code, see Table 5 for permitted values

error_description

Opt

Human-readable ASCII encoded text description of the error

error_uri

Opt

URI of a web page that includes additional information about the error

state

Cond

OAuth 2.0 state value. REQUIRED if the Authorization Request included the state parameter. Set to the value received from the Client.

Table 5: Error Codes for Authentication Error Response

Code

Description

OAuth 2.0 error codes

invalid_request

The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.

unauthorized_client

The client is not authorized to request an authorization code using this method

access_denied

The resource owner or Platform denied the request

unsupported_response_type

The Platform does not support obtaining an authorization code using this method

invalid_scope

The requested scope is invalid, unknown, or malformed

server_error

The Platform encountered an unexpected condition that prevented it from fulfilling the request. (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect.)

temporarily_unavailable

The Platform is currently unable to handle the request due to a temporary overloading or maintenance of the server. (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect.)

OpenID Connect Error Codes (in addition to the above)

interaction_required

The Authorization ServerPlatform requires End-User interaction of some form to proceed. This error MAY be returned when the prompt parameter value in the Authentication Request is none, but the Authentication Request cannot be completed without displaying a user interface for End-User interaction.

login_required

The Platform requires End-User authentication. This error MAY be returned when the prompt parameter value in the Authentication Request is none, but the Authentication Request cannot be completed without displaying a user interface for End-User authentication.

account_selection_required

The End-User is REQUIRED to select a session at the Platform. The End-User MAY be authenticated at the Platform with different associated accounts, but the End-User did not select a session. This error MAY be returned when the prompt parameter value in the Authentication Request is none, but the Authentication Request cannot be completed without displaying a user interface to prompt for a session to use

consent_required

The Platform requires End-User consent. This error MAY be returned when the prompt parameter value in the Authentication Request is none, but the Authentication Request cannot be completed without displaying a user interface for End-User consent

invalid_request_uri

The request_uri in the Authorization Request returns an error or contains invalid data

3.5 Token Endpoint

3.5.1 Token Request

A Token request is used to obtain an Access Token and an ID Token. The Partner Service (client) sends a Token Request to the Token Endpoint to obtain a Token Response.

Confidential Clients MUST authenticate to the Token Endpoint using the authentication method registered for its client_id (see section 6.2.1)

The Client sends the parameters to the Token Endpoint using the HTTP POST method and the Form Serialization – the request must be sent using TLS v1.2 or above

Table 6: Token Request Parameters

Parameter

Req?

Description

grant_type

Mand

Value MUST be set to “authorization_code”

code

Mand

The authorization code previously received from the Platform

redirect_uri

Mand

Required – MUST match the “redirect_uri” parameter that was included in the authorization request.

client_id

Cond

Mandatory for Public Clients

Not required for Confidential Clients

client_assertion_type

Mand

Mandatory for Confidential Clients

urn:ietf:params:oauth:client-assertion-type:jwt-bearer

client_assertion

Mand

Mandatory for Confidential Clients

A signed JWT presented for Client Authentication, as per

https://tools.ietf.org/html/rfc7523
(Note the “iss” and “sub” claim must equal the client_id and the “aud” must contain the token endpoint URL)
The assertion must be signed using the private key of the client, agreed during onboarding

3.5.2 Token Request Validation

References:

OpenID Connect Core Specification [1], s3.1.3.2

Enhancing OAuth security for mobile applications with PKCE [4]

The Token Request is validated as described in the OpenID Connect Core Specification [1], section 3.1.3.2 and the client_assertion is validated as per https://tools.ietf.org/html/rfc7523 for Client Authentication.

3.5.3 Token Response

3.5.3.1 Successful Response

References:

OpenID Connect Core Specification [1], section 3.1.3.3

RFC6749 – The OAuth 2.0 Authorization Framework [5],.
s4.1.4

After receiving and validating a valid and authorised Token request from the client, the Token Endpoint returns a response which includes an ID Token and an Access Token. The response uses the “application/json” media type.

Table 7: Token Response: HTTP headers & values

Header Name

Value

Cache-Control

no-store

Pragma

no-cache

Table 12: Token Response

Parameter

Req?

Description

access_token

Mand

Signed JWT which encodes the Access Token, see sections 4.1 and 4.3

token_type

Mand

Must be value “bearer”

refresh_token

n/a

Not currently supported

expires_in

Opt

Recommended.

The lifetime in seconds of the access token. If omitted, the Platform SHOULD provide the expiration time via other means or document the default value

scope

Cond

OPTIONAL, if identical to the scope requested by the client;

otherwise, REQUIRED

id_token

Mand

Signed JWT which encodes the ID Token – see sections Error! Reference source not found. and Error! Reference source not found.

3.5.3.2 Error Response

References:

OpenID Connect Core Specification [1], s3.1.3.4

RFC6749 – The OAuth 2.0 authorization framework [5],
s5.2

If the Token Request is invalid or unauthorized, the Platform constructs the error response. The parameters of the Token Error Response are defined as in Section 5.2 of OAuth 2.0 [RFC6749]. The HTTP response body uses the application/json media type with HTTP response code of 400.

URI of a web page that includes additional information about the error

Table 10: Error Codes for Authentication Error Response

Code

Description

OAuth 2.0 error codes

invalid_request

The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed.

The Platform MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported. If the client attempted to authenticate via the “Authorization” request header field, the Platform MUST respond with an HTTP 401 (Unauthorized) status code and include the “WWW-Authenticate” response header field matching the authentication scheme used by the client.

invalid_grant

The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.

unauthorized_client

The authenticated client is not authorized to use this authorization grant type.

unsupported_grant_type

The authorization grant type is not supported by the authorization serverPlatform.

invalid_scope

The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner

3.5.4 Token Refresh Request

References:

OpenID Connect Core Specification [1], s3.1.3.1

RFC6749 – The OAuth 2.0 authorization framework [5],
s4.1.3

Not currently supported

3.6 UserInfo Endpoint

References:

OpenID Connect Core Specification [1], s5.3

The UserInfo Endpoint is an OAuth 2.0 Protected Resource that returns Claims about the authenticated End-User. To obtain the requested Claims about the End-User, the Client makes a request to the UserInfo Endpoint using an Access Token obtained through OpenID Connect Authentication. These Claims are represented by a JSON object that contains a collection of name and value pairs for the Claims.

3.6.1 UserInfo Request

References:

OpenID Connect Core Specification [1], s5.3.1

RFC6750: OAuth 2.0 Bearer Token Usage [6], s2

The Client sends the UserInfo Request using either HTTP GET (recommended) or HTTP POST.

The Access Token obtained from an OpenID Connect Authentication Request MUST be sent as a Bearer Token using the Authorization header field, per Section 2 of OAuth 2.0 Bearer Token Usage.

3.6.2 UserInfo Response

3.6.2.1 Successful Response

Reference:

OpenID Connect Core Specification [1], s5.3.2

The UserInfo Claims MUST be returned as the members of a JSON object. If a Claim is not returned, then that Claim Name SHOULD be omitted from the JSON object representing the Claims; it SHOULD NOT be present with a null or empty string value.

Reference:

OpenID Connect Core Specification [1], s5.1

The NHS login Service supports standard and additional claims as follows:

Table 11: NHS login Supported Claims

issYIssuer Identifier for the Issuer of the responseNHS login Additional Claims

Claim

Supported

Description

OpenID Connect Standard Claims

aud

Y

The Partner Service identifier

sub

Y

Subject – Identifier for the End-User at the Issuer.

family_name

Y

Surname(s) or last name(s) of the End-User

given_name

Y

First name(s) of the End-User.

This information will only be returned where the user’s identity has been verified AND the profile_extended scope is requested AND the user consents to the claim being returned

Email

Y

End-User’s preferred e-mail address

Present if the email scope was present in the request

email_verified

Y

True if the End-User’s e-mail address has been verified; otherwise false

Present if the email scope was present in the request

phone_number

Y

End-User’s preferred phone number

Present if the phone scope was present in the request AND the user consents to the claim being returned

phone_number_verified

Y

True if the End-User’s phone number has been verified; otherwise false

Present if the phone scope was present in the request AND the user consents to the claim being returned

birthdate

Y

End-User’s date of birth in ISO8601‑2004 format:

YYYY-MM-DD

Address

Y

A json object representing the End-User’s home address as held in the NHS Personal Demographics Service.

This information will only be returned where the user’s identity has been verified AND the address scope is requested AND the user consents to the claim being returned

NOTE: Due to the possibility of token substitution attacks (see Ref [1], Section 16.11), the UserInfo response is not guaranteed to be about the End-User identified by the sub (subject) element of the ID Token. The sub Claim in the UserInfo Response 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.

Upon receipt of the UserInfo Request, the UserInfo Endpoint MUST return the JSON Serialization of the UserInfo Response in the HTTP response. The content-type of the HTTP response MUST be “application/json; the response body SHOULD be encoded using UTF-8.

3.6.2.2 Error Response

References:

RFC6750: OAuth 2.0 Bearer Token Usage [6], s3

When an error condition occurs, the UserInfo Endpoint returns an Error Response, as defined in Section 3 of Oauth 2.0 Bearer Token Usage, which MUST include the HTTP “WWW-Authenticate” response header field.

Table 12: UserInfo Error Response

Parameter

Req?

Description

Error

Mand

Error code, see Table 5 for permitted values

error_description

Opt

Human-readable ASCII encoded text description of the error

Table 17: Error Codes for UserInfo error response

Code

Description

OAuth 2.0 error codes

invalid_request

The request is missing a required parameter, includes an unsupported parameter or parameter value, repeats the same parameter, uses more than one method for including an access token, or is otherwise malformed. The resource server SHOULD respond with the HTTP 400 (Bad Request) status code.

invalid_token

The access token provided is expired, revoked, malformed, or invalid for other reasons. The resource SHOULD respond with the HTTP 401 (Unauthorized) status code. The client MAY request a new access token and retry the protected resource request.

insufficient_scope

The request requires higher privileges than provided by the access token. The resource server SHOULD respond with the HTTP 403 (Forbidden) status code and MAY include the “scope” attribute with the scope necessary to access the protected resource

The following is a non-normative example of a UserInfo Error Response:

4 Tokens

An ID Token is a security token that contains Claims about the Authentication of an End-User by the Platform, when using a Client and potentially other requested Claims. The Access Token is a credential that can be used by an application to access an API – initially the UserInfo endpoint.

The NHS login Platform uses signed Java Web Tokens (JWTs) for ID Tokens and Access Tokens. Other tokens, for example Refresh tokens are not supported.

4.1 JWT header

References:

RFC7519 – JSON Web Token (JWT) [7]

RFC7515 – JSON Web Signature (JWS) [8]

The JWT header will contain the following claims:

Table 14: JWT Header

Claim

Req?

Name

Description

alg

Mand

Algorithm used for signing the JWT

“RS512” – RSASSA-PKCS1-v1_5 with the SHA-512 hash algorithm

typ

Mand

Type

“JWT”

jku

n/a

JWK Set URL

Not supported, keys are communicated outside the JWT, see Ref [1], s2

jwk

n/a

JSON Web Key

Not supported, keys are communicated outside the JWT, see Ref [1], s2

x5u

n/a

X.509 URL

Not supported, keys are communicated outside the JWT, see Ref [1], s2

x5c

n/a

X.509 Certificate Chain

Not supported, keys are communicated outside the JWT, see Ref [1], s2

4.2 ID Token Payload

References:

OpenID Connect Core Specification [1], section 2

The following claims are used within the ID Token for all OAuth 2.0 flows used by OpenID Connect:

Table 15: id_token claims

When a max_age request is made or when auth_time is requested as an Essential Claim, then this Claim is REQUIRED; otherwise, its inclusion is OPTIONAL. (The auth_time Claim semantically corresponds to the OpenID 2.0 PAPE [10] auth_time response parameter.)

Claim

Req?

Name

Description

Standard Claims

iss

Mand

Issuer identifier for the issuer of the response

The iss value is a case sensitive URL using the https scheme that contains scheme, host, and optionally, port number and path components and no query or fragment components.

Sub

Mand

Subject identifier

A locally unique and never reassigned identifier within the Issuer for the End-User, which is intended to be consumed by the Client, e.g., 24400320 or

It MUST contain the Oauth 2.0 client_id of the Partner Services as an audience value. It MAY also contain identifiers for other audiences. In the general case, the aud value is an array of case sensitive strings. In the common special case when there is one audience, the aud value MAY be a single case sensitive string

Exp

Mand

Expiration time on or after which the ID Token MUST NOT be accepted for processing

The processing of this parameter requires that the current date/time MUST be before the expiration date/time listed in the value. Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. See RFC 3339 [RFC3339] for details regarding date/times in general and UTC in particular

Iat

Mand

Time at which the JWT was issued

Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. See RFC 3339 [9] for details regarding date/times in general and UTC in particular

Iti

Mand

JWT unique identifier

Value is unique to each token created by the issuer

auth_time

Cond

Time when the End-User authentication occurred

nonce

Cond

String value used to associate a Client session with an ID Token, and to mitigate replay attacks

The value is passed through unmodified from the Authentication Request to the ID Token.

If present in the ID Token, Clients MUST verify that the nonce Claim Value is equal to the value of the nonce parameter sent in the Authentication Request.

If present in the Authentication Request, the Platform MUST include a nonce Claim in the ID Token with the Claim Value being the nonce value sent in the Authentication Request.

The Platform will perform no other processing on nonce values used.

The nonce value is a case sensitive string

acr

n/a

Authentication Context Class Reference

Not Supported – superseded by vot

amr

n/a

Authentication Methods References

Not currently supported

azp

n/a

Authorized party – the party to which the ID Token was issued

Not currently supported

vot

Mand

Vectors of Trust

The level to which the user’s identity has been verified.

See s5.1 for values

vtm

Mand

Vector Trust Mark

https URI of the vtm claim

See s5.1.5

family_name

Cond

Family Name

Surname(s) or last name(s) of the End-User

birthdate

Cond

Birthdate

If the user’s date of birth is available, it is returned in ISO8601‑2004 format, YYYY-MM-DD

NHS login extensions

nhs_number

Cond

NHS number

If the user’s NHS number is known, then it MUST be included. Will be represented as a 10-digit string.

ID Tokens MAY contain other Claims. Any Claims used that are not understood MUST be ignored by the RP.

The following is a non-normative example of the set of Claims (the JWT Claims Set) in an ID Token:

4.3 Access Token Payload

The iss value is a case sensitive URL using the https scheme that contains scheme, host, and optionally, port number and path components and no query or fragment components.

sub

Mand

Subject Identifier

A locally unique and never reassigned identifier within the Issuer for the End-User, which is intended to be consumed by the Client, e.g., 24400320 or
AitOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4. It MUST NOT exceed 255 ASCII characters in length.The sub value is a case sensitive string

aud

Mand

Audience(s) that this ID token is intended for

It MUST contain the Oauth 2.0 client_id of the Partner Service as an audience value. It MAY also contain identifiers for other audiences. In the general case, the aud value is an array of case sensitive strings. In the common special case when there is one audience, the aud value MAY be a single case sensitive string

exp

Mand

Expiration time on or after which the ID Token MUST NOT be accepted for processing

The processing of this parameter requires that the current date/time MUST be before the expiration date/time listed in the value. Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. See RFC 3339 [RFC3339] for details regarding date/times in general and UTC in particular

iat

Mand

Time at which the JWT was issued

Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. See RFC 3339 [RFC3339] for details regarding date/times in general and UTC in particular

iti

Mand

JWT unique identifier

Value is unique to each token created by the issuer

scope

Mand

Scopes that the access_token provides access to

A space-separated list of scopes for which the token is issued. This list will be scopes requested in the authentication request (see s3.4.1) or a subset of them

auth_time

Cond

Time when the End-User authentication occurred

Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.

When a max_age request is made or when auth_time is requested as an Essential Claim, then this Claim is REQUIRED; otherwise, its inclusion is OPTIONAL. (The auth_time Claim semantically corresponds to the OpenID 2.0 PAPE [10] auth_time response parameter.)

acr

n/a

Authentication Context Class Reference

Not supported – superseded by vot

vot

Mand

Vectors of Trust

The level to which the user’s identity has been verified.

See s5.1 for values

vtm

Mand

Vector Trust Mark

https URI of the vtm claim

See s5.1.5

NHS login extensions

nhs number

Cond

NHS Number

If the user’s NHS number is known, then it MUST be included. Will be represented as a 10-digit string.

reason_for_request

Opt

The identified the purpose for which the request is being made.

Purpose for which access is being requested. Will contain “patientaccess”. See [11]

requesting_system

Opt

Identifier for the system or device making the request

This is an identifier for the deployed client system that has been authorised to make API calls. In the case of Spine-enabled clients (or those using the SSP to broker API calls), this will be a Spine Accredited System ID (ASID)

The naming system prefix for the ASID will be https://fhir.nhs.uk/Id/accredited-system

See [11]

requesting_patient

Opt

NHS Number

If this authorisation relates to a citizen, this attribute will hold the NHS Number of the citizen

The naming system prefix for the NHS Number will be http://fhir.nhs.net/Id/nhs-number

See [11]

4.4 JOSE Signing

References:

RFC7519 – JSON Web Token (JWT) [7]

RFC7515 – JSON Web Signature (JWS) [8]

The JWT will be signed using the RSASSA-PKCS1-v1_5 with the SHA-256 hash algorithm (“RS512”)

NHS login supports Vectors of Trust for Identification Verification and Authentication. Credential Management and Assertion Presentation are out of scope

5.1.1 Verification of Identity Levels

The NHS login supports the following levels of identification verification. These are based upon ‘DCB3051 Identity Verification and Authentication Standard for Digital Health and Care Services’ [12] and GPG45

Table 17: NHS login Verification Levels

Value

Description

P0

No Identity proofing

This maps to ‘Verification – None’ within DCB3051

P3

Identity proven via GPG45 LOA L1

P5

Knowledge-based verification ONLY

This maps to ‘Verification – Medium’ within DCB3051

P6

Verified to P5 with some additional checks or assertion from a trusted source (such as healthcare worker who has an established relationship with the citizen)

P7

Identity proven via GPG45 LOA L2

P9

Physical comparison

This maps to ‘Verification – High’ within DCB3051

5.1.2 Authentication Credentials

NHS login supports the following types of authentication credentials. Note that the credential component may occur more than once

Table 18: NHS login Authentication Context Class

Value

Description

Cp

Password-based

The user is in possession of a secret (for example a password, PIN, etc) belonging to the legitimate account holder.

Cd

Registered device

The user is in possession of a device which has previously been associated with their account – delivery/use of the device is by identifiers only

Ck

Shared Cryptographic key within a Registered Device

The user is in possession of a device which has previously been associated with their account – delivery/use of the device is by a shared key

Cm

Asymmetric Cryptographic key within a Registered Device

The user is in possession of a device which has previously been associated with their account – delivery/use of the device is by cryptographic proof of key possession using asymmetric key, such as a FIDO-compliant device

5.1.3 Requesting Vectors of Trust values

The client MAY request a set of acceptable VoT values with the “vtr” (vector of trust request) claim request as part of the Authentication Request. The value of this field is an array of JSON strings, each string identifying an acceptable set of vector components.

The component values within each vector are ANDed together while the separate vectors are ORed together. For example, a list of vectors in the form ‘[“P9.Cp.Cd “, “P9.Ck”]’ is stating that either the full set of “P9 AND Cp AND Cd” simultaneously OR the full set of “P9 AND Ck” simultaneously are acceptable for this transaction.

Vector request values MAY omit components, indicating that any value is acceptable for that component category, including omission of that component in the response vector.

5.1.4 Returning Vectors of Trust values

The vector is sent as a string within the “vot” (vector of trust) claim in the ID and Access tokens. The trustmark that applies to this vector MUST be sent as an HTTPS URL in the “vtm” (vector trust mark) claim to provide context to the vector.

For example, part of the body of an ID token claiming “Medium Assurance Identity, authenticated user via password and registered device identifier” could look like this JSON object payload of the ID token.

The body of the token is signed using JOSE, as per the OpenID Connect specification. By putting the “vot” and “vtm” values inside the token, the vector and its context are strongly bound to the federated credential represented by the token.

5.1.5 Trustmark

References

Vectors of Trust, Draft RFC [3], section 5

The Trustmark provides a list of claims that NHS login supports. This enables the client to verify which components of a trust framework NHS login supports and hence their trustworthiness

The NHS login Trustmark will be self-hosted.

The following is a non-normative example a Trustmark based on s5.1.3 and 5.1.4 above:

5.1.6 Profiles

Aligning the above to the standard DCB3051 Identity Verification and Authentication Standard for Digital Health and Care Services [12] brings a standard set of vectors supported by the NHS login Service, described in the table below

The service requires Medium Verification and High Authentication, with SSO allowed. The service sends the following as acceptable Vectors in the ‘vtr’ parameter:
“[“P5.Cp.Cd”, “P5.Cp.Ck” , “P5.Cm”, “P9.Cp.Cd”, “P9.Cp.Ck”, “P9.Cm”]”

5.1.6.3 Single Sign-on

If the user’s current sign-on session (if any), does not meet the requested Vectors of Trust (vtr) in the incoming request, then the user will be required to sign-in, in order to meet the requested vectors.

Also note that Single sign-on behaviour, or to refuse SSO-behaviour, can be controlled using the ‘prompt’ parameter on the initial authorisation request – see section 3.4.1.

6 Partner Services and Security

6.1 Partner Service Registration

Currently, Partner Services will be registered and onboarded into the NHS login Platform using a standard offline process.

The following information is required is required for the offline registration process:

Table 19: Client Metadata – supplied by client

Attribute

Description

Redirect URIs

List of Redirection URI values used by the Client.

The redirect_uri parameter value used in each Authorization Request MUST exactly match one of these registered Redirection URI values

Client Name

Name of the Client to be presented to the End-User

Public Key

A copy of the client’s public key is supplied. The public key must be in PEM format and represent a 2048-bit RSA keypair.

Scopes

Required scopes

On successful registration, the following information will be provided

Table 20: Client Metadata – allocated by NHS login

Attribute

Req?

Type

Description

client_id

Mand

String

Id for the client, allocated by the NHS login service

6.2 Partner Service authentication

Reference:

OpenID Connect Core Specification [1], section 9

6.2.1 Confidential Clients

Partner Services which are confidential clients will use the following authentication mechanism:

private_key_jwt, as per https://tools.ietf.org/html/rfc7523

The authentication mechanism of “none” is not supported for confidential clients

6.4 Client Redirects

The NHS login Platform will only allow redirect URIs which have been pre-agreed during the onboarding process.