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 for more details.

End-to-End Retrieval Process

The following diagram describes how information retrieval is facilitated through the SSP using a URL included in a pointer.

The diagram above depicts the step-by-step, end-to-end, process for retrieving information, as follows:

1. Consumer system queries the NRL to see if any pointers exist for the patient.
2. The NRL responds with a collection of pointers containing information about the patient.
3. Consumer system identifies a pointer that references information which could be of value for the provision of care.
4. Consumer system takes the URL property value from that pointer and uses this value to create a request to the provider system that holds the information.
5. Consumer system sends the request to the provider system via the SSP.
6. The SSP performs security checks against the consumer and then provider.
7. The request is forwarded onto the provider system.
8. Provider system receives and validates the request.
9. Provider system responds back to the SSP with the requested information, which is returned to the consumer.
10. Consumer system receives the information and processes it ready to display to the end user.

Requesting Information via the SSP

Endpoints which allow retrieval of information via the SSP MUST do so with a HTTPS GET 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:

For example:

GET https://[proxy_server]/https%3A%2F%2Fp1.nhs.uk%2FMentalHealthCrisisPlans%2Fda2b6e8a-3c8f-11e8-baae-6c3be5a609f5

HTTP Headers

The consumer and the provider’s endpoint MUST support the following HTTP request headers:

For more information on the SSP required headers or full technical details, please refer to the Spine Secure Proxy Implementation Guide.

The provider endpoint MUST NOT require any custom headers to be passed with the request, unless explicitly stated in the relevant format specification.

Response

Success

A successful request MUST:

• return a 200 OK HTTP status code.
• return a response body containing the requested information in the format described in the format metadata attribute on the pointer. See Supported Formats for more details.

Failure

A failed request:

• MUST return an error type HTTP status code (i.e. 4xx or 5xx).
• SHOULD return a response body with diagnostic details.

Authentication and Authorisation

Systems that interact with the SSP MUST meet the secure connection requirements of the SSP. Following completion of assurance, providers will be supplied with an X.509 Certificate.

Consumer systems MUST ensure users are authenticated and authorised, using an appropriate access control mechanism, before retrieving information.

Consumers MUST generate and supply a JWT access token with each request they initiate using the standard Authorization HTTP header. Details of these requirements can be found on the JSON Web Token Guidance page. The JWT can be used in provider systems for auditing purposes. Providers are not required to perform any further authentication or authorisation.

More details can be found on the Security page.

Provider Retrieval Endpoints

Endpoints exposed by a provider for retrieval via the SSP must be registered on the Spine Directory Service (SDS). The requirements for registering endpoints on SDS are as follows:

1. The FQDN MUST be of the form nrl-[ODS_code].[supplier].thirdparty.nhs.uk, where the ODS code can be for the supplier or information owner organisation, depending on the deployment. Following completion of assurance, providers will be supplied with an FQDN.
2. Every system MUST have a unique ASID for each organisation. For example, the same system deployed into three organisations would be represented by three unique ASIDs. See below for further details.
3. All interactions with the SSP MUST be over port 443.
4. Endpoints MUST NOT include explicit port declarations (e.g. :443).
5. Endpoints MUST have been registered with the SSP retrieval interaction ID urn:nhs:names:services:nrl:DocumentReference.content.

See the Spine Core specification for further detail on registering provider endpoints.

Providers MUST ensure that the Information Owner ODS code on the pointer metadata matches the ODS code for the endpoint registered in SDS. This is required to enable consumers to perform an SDS lookup to obtain the provider ASID and populate the Ssp-To header in the retrieval request. Each information owner requires an individual endpoint to be registered, therefore where multiple information owners expose records via a single deployment, it is recommended that the format of the endpoint is as follows:

For example:

GET https://nrl-ODS1.supplier.thirdparty.nhs.uk/ODS2/Binary/e73277f9-89e5-4d8c-8457-107e30fcb5a7

Audit Requirements

Consumers and providers are required to keep an audit trail of requests 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.)
• Providers MUST keep an audit trail of requests received from consumers (to retrieve records/documents etc.) and their corresponding responses*.

* It is not necessary for a provider to keep an audit trail of the response payload returned to consumers, however, providers MUST be able to provide details of the record returned if required for medico-legal purposes.

In addition, the SSP is required to keep an audit trail of requests and responses that flow through these services and providers may request audit trail data from NHS Digital about any pointers they own/maintain.

Audit Logs

The following sections detail what information each actor (Consumer/Provider) MUST record in their audit logs. For details of each required attribute, see the Audit Log Attributes table below.

Consumer Document/Record Retrieval

Consumers MUST record the following in audit logs for each document/record retrieval request to a provider via the SSP:

Provider Document/Record Retrieval

Providers MUST record the following in audit logs for each record retrieval request from a consumer via the SSP:

Audit Log Attributes

The following table details the audit log attributes and the source of the value for the attribute.