diff --git a/specification/record-locator/consumer.yaml b/specification/record-locator/consumer.yaml index 930cb19..75589f2 100644 --- a/specification/record-locator/consumer.yaml +++ b/specification/record-locator/consumer.yaml @@ -250,21 +250,100 @@ info: NRL is primarily concerned with the registering and retrieval of pointers. As per the [registry/repository pattern] (https://digital.nhs.uk/developer/architecture/integration-patterns-book/patterns#registry-repository), following the retrieval of a pointer, the retrieval of an associated document/record may take place. In some circumstances information (or documents) are held in disparate systems. The registry-repository pattern resolves this by providing pointers with details that can be used to contact the organisation where the record is held, or directly retrieve the record from source, if authorised to do so. Most documents NRL pointers point to are retrievable using the Spine Secure Proxy [(SSP)](https://digital.nhs.uk/services/gp-connect/develop-gp-connect-services/integrate-with-spine/spine-secure-proxy). For example, all pointers of the category 'care plan' currently point to unstructured PDF documents, retrievable using SSP. To connect to the Spine Secure Proxy (SSP), you will need: - *An ASID for your organisation - *A FQDN and CSR for your endpoint/application - *Document Content Read Permissions for your ASID - *Internet Catbag Permissions for SSP (if accessing it over the internet for your ASID) + + * An ASID for your organisation + * A FQDN and CSR for your endpoint/application + * Document Content Read Permissions for your ASID + * Internet Catbag Permissions for SSP (if accessing it over the internet for your ASID) If you have any questions on how to get an FQDN or how to generate a CSR, please email [ITOC](mailto:itoc.supportdesk@nhs.net). An example FQDN would be spine.example.record-locator.nhs.uk In order to get an ASID, please complete this [form](https://digital.nhs.uk/services/path-to-live-environments/path-to-live-forms/combined-endpoint-and-service-registration-request) - You will need to tick "create an endpoint including certificate " in section 2, use FQDN in section 3 and section 4, tick 'CMA endpoint' in section 5 (manufacturer's details are not mandatory here), and leave sections 6 and 7 blank. + You will need to tick "create an endpoint including certificate" in section 2, use FQDN in section 3 and section 4, tick 'CMA endpoint' in section 5 (manufacturer's details are not mandatory here), and leave sections 6 and 7 blank. You should receive an email with your ASID and generated Certificate upon completing this form. Once you have done this, you will need to ask for the 'internet' (if accessing it over the internet for your ASID) Catbag and 'Document Content Read' interaction permissions to be added to your ASID. You can request these permissions by emailing [ITOC](mailto:itoc.supportdesk@nhs.net) If you are a GP system supplier looking to onboard to retrieve 'Lloyd George Record Folder' pointers, then SSP will not be used. Instead, you will need to onboard to the Large Document Retrieval (LDR) retrieval proxy. + ## Spine Secure Proxy (SSP) + + Information retrieval is an interaction between a consumer and a provider; routing and receiving requests via the SSP allows both parties to be ignorant of each other’s authentication and authorisation mechanisms, as the SSP handles the other side of the transaction. + The SSP is a content agnostic forward proxy, which is used to control and protect access to health systems. It provides a single security point for both authentication and authorisation for systems. See the [SSP specification](https://developer.nhs.uk/apis/spine-core/ssp_overview.html) for more details. + + **Requesting Information via the SSP** + Endpoints which allow retrieval of information via the SSP MUST do so with a [HTTPS GET](https://www.rfc-editor.org/rfc/rfc9110.html) request, to the URL contained within the NRL pointer. + The provider endpoint MUST NOT require any custom parameters to be passed with the request, unless explicitly stated in the relevant format specification. + + For a consumer to retrieve information via the SSP, the consumer MUST percent encode the content.attachment.url property from the NRL pointer and prefix it with the SSP server URL as follows: GET https://[proxy_server]/[percent_encoded_provider_endpoint_url] + For example: GET https://[proxy_server]/https%3A%2F%2Fp1.nhs.uk%2FMentalHealthCrisisPlans%2Fda2b6e8a-3c8f-11e8-baae-6c3be5a609f5. + + ## Auditing + + This section outlines the audit and provenance requirements for data exchanged over NRL interfaces. + All Consumers and Providers must maintain an audit trail of requests to and responses related to the retrieval of records and documents. + * Consumers MUST keep an audit trail of requests to and responses from provider systems (to retrieve records/documents etc). + + ### Access Token (JWT) + Consumers and Producers MUST generate and supply a valid JWT access token with every request they initiate. This token must be supplied via the standard Authorization HTTP header for auditing purposes. + Any request submitted without an Authorization header that meets the specified JWT requirements will be rejected. + Refer to the JSON Web Token Guidance for detailed specifications. + + ### Audit Logs + This section details the audit logging requirements that a consumer must record in their audit logs. For definitions of each data element referenced below, see the Audit Log Attributes section. + + **Consumer Pointer Search/Read** + Consumers MUST record and store the following information in audit logs for each NRL search interactions (GET): + + **For requests to the NRL** + * ASID + * HTTP Request URL + * HTTP Verb + * NHS Number + * ODS Code + * Request Datetime + * User ID + + **For responses from the NRL** + * HTTP Response Body + * HTTP Status Code + * Response Datetime + + **Consumer Document/Record Retrieval** + Consumers MUST record the following in audit logs for each document/record retrieval request to a provider via the SSP: + + **For requests to providers** + * ASID + * HTTP Request URL + * NHS Number + * ODS Code + * Pointer Logical ID + * Request Datetime + * Trace ID + * User ID + + **For responses from providers** + * HTTP Response Body (if the request failed) + * HTTP Status Code + * Response Datetime + + **Audit Log Attributes** + The table below defines each audit log attribute and identifies the source from which its value must be obtained. + | Attribute | Source | + |------------|---------| + | ASID | The requesting_system from JWT. Use only the ASID portion, for example: https://fhir.nhs.uk/Id/accredited-system\|[ASID]. | + | HTTP Request URL | The URL of the NRL service that was called or the URL used for the record retrieval request, which includes the value of the content.attachment.url property defined on the associated NRL pointer. | + | HTTP Response Body | The body of the response message returned. | + | HTTP Status Code | Describes the response outcome: 2xx (Success), 4xx or 5xx (Failure). | + | NHS number | The patient identifier used in the pointer subject reference (for example, https://demographics.spineservices.nhs.uk/STU3/Patient/[nhsNumber]) or in a search query parameter. | + | ODS Code | The requesting_organization from JWT (only the ODSCode portion is required, for example, https://fhir.nhs.uk/Id/ods-organization-code\|[odsCode]). | + | Pointer Logical ID | The logical ID of the pointer (generated by the NRL), from which the retrieval request has been made. | + | Request Datetime | Timestamp when the audit log entry was created. | + | Response Datetime | Timestamp when the response was received from the NHS England service. | + | Trace ID | The consumer-generated ID of the retrieval request. This is only used for requests via the SSP and is for use in the Ssp-TraceID HTTP request header. | + | User ID | The requesting_user from JWT. This is not mandatory where the request is completed as a non-interactive process. | + + ## Change log For details of how this API has changed over time, see the [release history](https://github.com/NHSDigital/nrl-consumer-api/releases).