Access Tokens and Audit (JWT)

In order to access the NRLS clients MUST send an access token (JWT) with each request using the standard HTTP Authorization request header. The JWT MUST conform to the Spine JWT definition.

The claims of the NRLS JWT is the same as those defined in the Spine Core JWT however the rules that govern the validation of those claims are different. From an NRLS perspective the rules defined here override rules defined for the Spine Core. Where a Spine Core rule is not explicitly replaced here then the Spine Core rule stands.

Claims

In the Spine JWT definition the requesting_organistion claim is marked as optional however for NRLS this claim MUST be supplied.

Validation

Depending upon the client’s role (Provider or Consumer) the validation that is applied to the JWT varies. The following section is broken down into three parts –

1. Common – validation that is common across Providers and Consumers

2. Provider – validation rules that only apply where the client is a Provider

3. Consumer – validation rules that only apply where the client is a Consumer

Common Validation

Where there has been a validation failure then the following response will be returned to the client. In all instances the response will be the same however the diagnostics text will vary depending upon the nature of the error.

HTTP Code	issue-severity	issue-type	Details.Code	Details.Display	Diagnostics
400	error	structure	MISSING_OR_INVALID_HEADER	There is a required header missing or invalid	Note: See MISSING_OR_INVALID_HEADER Exception Scenarios

MISSING_OR_INVALID_HEADER Exception Scenarios:

Example 1: JWT missing – the Authorization header has not been supplied. The following response SHALL be returned to the client.

Diagnostics - The Authorisation header must be supplied

Example 2: JWT structure invalid – the Authorization header is present however the value is not a structurally valid JWT ie one or more of the required elements of header, payload and signature is missing.

Diagnostics - The JWT associated with the Authorisation header must have the 3 sections

Example 3: Mandatory claim missing – the Authorization header is present and the JWT is structurally valid however one or more of the mandatory claims is missing from the JWT

Diagnostics - The mandatory claim [claim] from the JWT associated with the Authorisation header is missing

Example 4: Claim’s value is invalid - the Authorization header is present and the JWT is structurally valid a mandatory claim is present in the JWT however it’s value is not valid. The table below shows the various checking that is applied to each claim in the JWT and the associated diagnostics message:

Claim being validated	Error scenario	Diagnostics
sub	No requesting_user has been supplied and the sub claims’ value does not match the value of the requesting_system claim	requesting_system ([requesting_system]) and sub ([sub]) claim’s values must match
sub	requesting_user has been supplied and the sub claims’ value does not match the value of the requesting_user claim	requesting_user ([requesting_user]) and sub ([sub]) claim’s values must match
reason_for_request	Reason for request does not have the value “directcare”	reason_for_request ([reason_for_request]) must be ‘directcare’
scope	Scope is not one of patient/DocumentReference.read OR patient/DocumentReference.write	scope ([scope]) must match either ‘patient/DocumentReference.read’ or ‘patient/DocumentReference.write’
requesting_system	Requesting system is not of the form [https://fhir.nhs.uk/Id/accredited-system/[ASID]	requesting_system ([requesting_system]) must be of the form [https://fhir.nhs.uk/Id/accredited-system/[ASID]]
requesting_system	Requesting system is not an ASID that is known to Spine	The ASID defined in the requesting_system ([ASID]) is unknown
requesting_organisation	Requesting organisation is not of the form [https://fhir.nhs.uk/Id/ods-organization-code/[ODSCode]	requesting_organisation ([requesting_ organisation]) must be of the form [https://fhir.nhs.uk/Id/ods-organization-code/[ODSCode]
requesting_organisation	Requesting organisation is not known to Spine	The ODS code defined in the requesting_organisation([ODS]) is unknown
requesting_organisation	Requesting organisation is not associated with the ASID from the requesting_system claim	requesting_system ASID ([ASID]) is not associated with the requesting_organisation ODS code ([ODS])

Precedence of requesting_user over requesting_system

If both the requesting_system and requesting_user claims have been provided, then the sub claim MUST match the requesting_user claim.

Provider Validation

No specific validation rules apply.

Consumer Validation

In the context of a Consumer request the requesting_user claim is mandatory.