Overview of how audit and provenance data is expected to be transported over the National Data Opt-out FHIR interfaces using JWT.

Cross Organisation Audit & Provenance using JWT

Consumer systems SHALL provide audit and provenance details in the HTTP authorization header as an oAuth bearer token (as outlined in RFC 6749) in the form of a JSON Web Token (JWT) as defined in RFC 7519.

An example such an HTTP header is given below:

     Authorization: Bearer jwt_token_string

In future, national authentication and authorisation services will be made available which will issue a bearer token which can be used directly for accessing this API. In the interim however, the client will need to construct the JWT themselves.

It is highly recommended that standard libraries are used for creating the JWT as constructing and encoding the token manually may lead to issues with parsing the token in Spine. A good source of information about JWT and libraries to use can be found on the JWT.io site

JSON Web Token (JWT)

Consumer system SHALL generate a new JWT for each API request.

Claim Mandatory Description Fixed Value Dynamic Value Specification / Example
iss Y Client systems issuer URI No Yes  
sub Y requesting_patient.identifier.value or requesting_practitioner.identifier.value or requesting_organization.identifier.value No Yes  
aud Y Authorization server’s token_URL https://clinicals.spineservices.nhs.uk No  
exp Y Expiration time integer after which this authorization MUST be considered invalid. exp (now + 5 minutes) UTC time in seconds  
iat Y The UTC time the JWT was issued by the requesting system iat now UTC time in seconds  
reason_for_request Y Purpose for which access is being requested patientaccess No  
scope Y Data being requested No consent/*.[create|read|update]  
requesting_system Y Identifier for the system or device making the request No System or Device Identifier  
requesting_patient N Citizen making the request No NHS Number  
requesting_user N Health or Social Care professional making the request No User Identifier  

JWT Generation

Consumer systems SHALL generate the JSON Web Token (JWT) consisting of three parts separated by dots (.), which are:

  • Header
  • Payload
  • Signature

Consumer systems SHALL generate an Unsecured JSON Web Token (JWT) using the “none” algorithm parameter in the header to indicate that no digital signature or MAC has been performed (please refer to section 3.6 of RFC 7513 for details).

  "alg": "none",
  "typ": "JWT"

Consumer systems SHALL generate an empty signature.

The final output is three Base64 strings separated by dots (note - there is some canonicalisation done to the JSON before it is base64 encoded, which the JWT code libraries will do for you).

For example:


JWT Payload Example

	"iss": "https://citizen-id.nhs.uk",
	"sub": "http://fhir.nhs.net/Id/nhs-number|6101231234",
	"aud": "https://clinicals.spineservices.nhs.uk",
	"exp": 1469436987,
	"iat": 1469436687,
	"reason_for_request": "patientaccess",
	"scope": "patient/consent.read patient/consent.write",
	"requesting_system": "https://fhir.nhs.uk/Id/accredited-system|200000000205",
	"requesting_patient": "http://fhir.nhs.net/Id/nhs-number|6101231234"

Additional information on the use of Access Tokens and Audit using JWT can be found at FHIR Spine Core API