Cross organisation audit and provenance
Governance
Provider systems MUST ensure that access to confidential data, including patient or clinical data, through the API must meet, as a minimum, the same requirements for information governance, authentication and authorisation, and auditing as that of the host system the API exposes.
Audit trail
For implementers that don’t have access to the GP SoC Framework / ‘IG Requirements for GP Systems V4’ requirements then the following extract of requirements covers the main audit trail requirements:
Provider systems MUST record in an audit trail all access and data changes within the system as a result of API activity in the same way that internal access and changes are required to be recorded.
Provider systems MUST ensure that all API transactions are recorded in an audit trail, and that audit trails must be subject to the standard IG audit requirements as defined in “IG Requirements for GP Systems V4” or as subsequently amended.
Provider systems MUST ensure failed or rejected API transactions are recorded with the same detail as for successful API requests, with error codes as per the error handling guidance.
Audit trail records MUST include the following minimum information:
- a record of the user identity. This is the User ID, Name, Role profile (including Role and Organisation, URP id when Smartcard authenticated) attribute values, obtained from the user’s Session structure
- a record of the identity of the authority – the person authorising the entry of, or access to data (if different from the user)
- the date and time on which the event occurred
- details of the nature of the audited event and the identity of the associated data (e.g. patient ID, message ID) of the audited event;
- a sequence number to protect against malicious attempts to subvert the audit trail by, for example, altering the system date
- audit trail records should include details of the end-user device (or system) involved in the recorded activity
Audit trails MUST be enabled at all times and there MUST NOT be means for users, or any other individuals, to disable any Audit Trail.
Provenance
Provider systems MUST ensure that all additions, amendments or logical deletions to administrative and clinical data made via an API is clearly identified with information regarding the provenance of the data (e.g. timestamp, details of Consumer system, details of user (including role), so it is clear which information has been generated through an API rather than through the Provider system itself.
Provider systems MUST record the following provenance details of all API personal and sensitive personal data recorded within the system:
- author details (identified through unique ID), including name and role
- data entered by (if different from author)
- date & time (to the second) entered
- originating organisation
- API interaction
Legal processing
Provider systems MUST ensure that data provided to Consumer systems only include data for which the GP practice acts as Data Controller.
Patient dissent
Provider systems MUST ensure that Patient Consent is respected (i.e. where express dissent is recorded then data is not shared).
Cross organisation audit and provenance transport
Bearer token
Consumer systems MUST 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
Provider systems MUST respond to oAuth Bearer Token errors in line with RFC 6750 - section 3.1.
JSON Web Tokens (JWT)
- Consumer system MUST generate a new JWT for each API request containing the claims outlined in the table below
- Where the claim contains a FHIR resource the FHIR resource should conform to the GP Connect FHIR resource profiles outlined on the FHIR Resources page
- An exception to this requirement is that in the
requesting_practitioner
claim thePractitioner
resource should contain an identifier with the system"http://fhir.nhs.net/sds-user-id
rather than the system required by the resource profilehttp://fhir.nhs.net/Id/sds-user-id
. This is required as there was an error during testing and assurance which resulted in the providers validate that the identifier in the resource has the incorrect value, so for consumers to make a successful call the incorrect system value needs to be included.
- An exception to this requirement is that in the
Claim | Priority | Description | Fixed Value | Dynamic Value |
---|---|---|---|---|
iss | R | Requesting systems issuer URI | No | Yes |
sub | R | ID for the user on whose behalf this request is being made. Matches requesting_practitioner.id |
No | Yes |
aud | R | Authorization server’s token_URL |
https://authorize.fhir.nhs.net/token |
No |
exp | R | Expiration time integer after which this authorization MUST be considered invalid. | exp |
(now + 5 minutes) UTC time in seconds |
iat | R | The UTC time the JWT was created by the requesting system | iat |
now UTC time in seconds |
reason_for_request | R | Purpose for which access is being requested | directcare |
No |
requested_record | R | The FHIR patient resource being requested (i.e. NHS Number identifier details) | No | FHIR Patient1 OR FHIR Organization2 |
requested_scope | R | Data being requested2 | patient/*.[read|write] OR organization/*.[read|write] |
No |
requesting_device | R | FHIR device resource making the request | No | FHIR Device1 |
requesting_organization | R | FHIR organisation resource making the request | No | FHIR Organization1+4 |
requesting_practitioner | R | FHIR practitioner resource making the request | No | FHIR Practitioner1+3 |
1 Minimal FHIR resource to include any relevant business identifier(s).
2 Patient scope for patient centric APIs (i.e. Get Care Record and Patient’s Appointments, Patient Task) or scope for organisation centric APIs (i.e. Get Organization Schedule)
3 To contain the practitioners local system identifier(s) (i.e. login details / username). Where the user has both a local system ‘role’ as well as a nationally-recognised role, then the latter MUST be provided. Default usernames (for example, referring to systems or groups) MUST NOT be used in this field.
4 The requesting organisation resource MUST refer to the care organisation from where the request originates rather than any other organisation which may host hardware or software, route requests to Spine, and/or hold the endpoint registration.
JWT generation
Consumer systems MUST generate the JSON Web Token (JWT) consisting of three parts separated by dots (.), which are:
- header
- payload
- signature
Consumer systems MUST 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 MUST generate an empty signature.
The final output is three base64url encoded strings separated by dots.
For example:
eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0.eyJpc3MiOiJodHRwOi8vZWMyLTU0LTE5NC0xMDktMTg0LmV1LXdlc3QtMS5jb21wdXRlLmFtYXpvbmF3cy5jb20vIy9zZWFyY2giLCJzdWIiOiIxIiwiYXVkIjoiaHR0cHM6Ly9hdXRob3JpemUuZmhpci5uaHMubmV0L3Rva2VuIiwiZXhwIjoxNDgxMjUyMjc1LCJpYXQiOjE0ODA5NTIyNzUsInJlYXNvbl9mb3JfcmVxdWVzdCI6ImRpcmVjdGNhcmUiLCJyZXF1ZXN0ZWRfcmVjb3JkIjp7InJlc291cmNlVHlwZSI6IlBhdGllbnQiLCJpZGVudGlmaWVyIjpbeyJzeXN0ZW0iOiJodHRwOi8vZmhpci5uaHMubmV0L0lkL25ocy1udW1iZXIiLCJ2YWx1ZSI6IjkwMDAwMDAwMzMifV19LCJyZXF1ZXN0ZWRfc2NvcGUiOiJwYXRpZW50LyoucmVhZCIsInJlcXVlc3RpbmdfZGV2aWNlIjp7InJlc291cmNlVHlwZSI6IkRldmljZSIsImlkIjoiMSIsImlkZW50aWZpZXIiOlt7InN5c3RlbSI6IldlYiBJbnRlcmZhY2UiLCJ2YWx1ZSI6IkdQIENvbm5lY3QgRGVtb25zdHJhdG9yIn1dLCJtb2RlbCI6IkRlbW9uc3RyYXRvciIsInZlcnNpb24iOiIxLjAifSwicmVxdWVzdGluZ19vcmdhbml6YXRpb24iOnsicmVzb3VyY2VUeXBlIjoiT3JnYW5pemF0aW9uIiwiaWQiOiIxIiwiaWRlbnRpZmllciI6W3sic3lzdGVtIjoiaHR0cDovL2ZoaXIubmhzLm5ldC9JZC9vZHMtb3JnYW5pemF0aW9uLWNvZGUiLCJ2YWx1ZSI6IltPRFNDb2RlXSJ9XSwibmFtZSI6IkdQIENvbm5lY3QgRGVtb25zdHJhdG9yIn0sInJlcXVlc3RpbmdfcHJhY3RpdGlvbmVyIjp7InJlc291cmNlVHlwZSI6IlByYWN0aXRpb25lciIsImlkIjoiMSIsImlkZW50aWZpZXIiOlt7InN5c3RlbSI6Imh0dHA6Ly9maGlyLm5ocy5uZXQvc2RzLXVzZXItaWQiLCJ2YWx1ZSI6IkcxMzU3OTEzNSJ9LHsic3lzdGVtIjoibG9jYWxTeXN0ZW0iLCJ2YWx1ZSI6IjEifV0sIm5hbWUiOnsiZmFtaWx5IjpbIkRlbW9uc3RyYXRvciJdLCJnaXZlbiI6WyJHUENvbm5lY3QiXSwicHJlZml4IjpbIk1yIl19fX0.
JWT payload example
{
"iss": "https://[ConsumerSystemURL]",
"sub": "[PractitionerID]",
"aud": "https://authorize.fhir.nhs.net/token",
"exp": 1469436987,
"iat": 1469436687,
"reason_for_request": "directcare",
"requested_record": {
"resourceType": "Patient",
"identifier": [{
"system": "http://fhir.nhs.net/Id/nhs-number",
"value": "[NHSNumber]"
}]
},
"requesting_device": {
"resourceType": "Device",
"id": "[DeviceID]",
"identifier": [{
"system": "[DeviceSystem]",
"value": "[DeviceID]"
}],
"model": "[SoftwareName]",
"version": "[SoftwareVersion]"
},
"requesting_organization": {
"resourceType": "Organization",
"id": "[OrganizationID]",
"identifier": [{
"system": "http://fhir.nhs.net/Id/ods-organization-code",
"value": "[ODSCode]"
}],
"name": "Requesting Organisation Name"
},
"requesting_practitioner": {
"resourceType": "Practitioner",
"id": "[PractitionerID]",
"identifier": [{
"system": "http://fhir.nhs.net/sds-user-id",
"value": "[SDSUserID]"
},
{
"system": "[UserSystem]",
"value": "[UserID]"
}],
"name": {
"family": ["[Family]"],
"given": ["[Given]"],
"prefix": ["[Prefix]"]
},
"practitionerRole": [{
"role": {
"coding": [{
"system": "http://fhir.nhs.net/ValueSet/sds-job-role-name-1",
"code": "[SDSJobRoleName]"
}]
}
}]
}
}
Where the Practitioner has both a local system role as well as a Spine RBAC role, then the Spine RBAC role MUST be supplied
Example code
C#
External documents/policy documents
Name | Author | Version | Updated |
GPSoC IG Requirements for GP Systems | NHS Digital | v4.0 | 19/09/2014 |
GP Systems Interface Mechanism Requirements V 1 | NHS Digital | v0.10 |