Access Tokens (JWT)
Clients MUST send an access token (JWT) with each request to the NRL or the SSP using the standard HTTP Authorization request header. The JWT MUST conform to the Spine JWT definition.
The claims of the JWT are the same as those defined in the Spine Core JWT. However, the rules that govern the validation of those claims are different. From an NRL perspective, the rules defined here override rules defined for the Spine Core.
Where a Spine Core rule is not explicitly replaced here, the Spine Core rule stands.
Claims
In the Spine JWT definition, the requesting_organisation
claim is marked as optional. However, this claim MUST be supplied for all NRL and SSP requests.
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:
- Common – validation that is common across Providers and Consumers
- Provider – validation rules that only apply where the client is a Provider
- Consumer – validation rules that only apply where the client is a Consumer
Common Validation
Where there has been a validation failure, 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 that is 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 MUST 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. In other words, one or more of the required elements of header, payload, and signature is missing.
Diagnostics - The JWT associated with the Authorisation header must have all 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, the JWT is structurally valid, and a mandatory claim is present in the JWT, but its value is not valid. The following table 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 and 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 and sub claim’s values must match. |
reason_for_request |
Reason for request does not have the value “directcare”. |
reason_for_request must be “directcare”. |
scope |
For requests to the NRL: scope is not one of patient/DocumentReference.read or patient/DocumentReference.write . |
scope must match either patient/DocumentReference.read or patient/DocumentReference.write . |
scope |
For requests to the SSP: scope is not patient/*.read . |
scope must match patient/*.read . |
requesting_system |
Requesting system is not of the form https://fhir.nhs.uk/Id/accredited-system/[ASID] . |
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 must be known to Spine. |
requesting_organisation |
requesting_organisation is not of the form https://fhir.nhs.uk/Id/ods-organization-code/[ODSCode] . |
requesting_organisation must be of the form https://fhir.nhs.uk/Id/ods-organization-code/[ODSCode] . |
requesting_organisation |
The ODS code of the requesting_organisation is not known to Spine. |
The ODS code of the requesting_organisation must be known to Spine. |
requesting_organisation |
requesting_organisation is not associated with the ASID from the requesting_system claim. |
The requesting_system ASID must be associated with the requesting_organisation ODS code. |
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 for all NRL and SSP requests.