SSP Retrieval

Requirements and guidance for information retrieval interactions via the 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 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:

Consumer system queries the NRL to see if any pointers exist for the patient.
The NRL responds with a collection of pointers containing information about the patient.
Consumer system identifies a pointer that references information which could be of value for the provision of care.
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.
Consumer system sends the request to the provider system via the SSP.
The SSP performs security checks against the consumer and then provider.
The request is forwarded onto the provider system.
Provider system receives and validates the request.
Provider system responds back to the SSP with the requested information, which is returned to the consumer.
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:

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

Note: When creating pointers, providers MUST NOT prefix the pointer URL property with the SSP server URL and MUST NOT percent encode it. In other words, consumers are fully responsible for constructing the Spine proxy URL from the pointer URL.

HTTP Headers

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

Headers	Value
`Authorization`	The `Authorization` header will carry the base64url encoded JSON web token required for audit on the Spine - see JSON Web Token page for details.
`Ssp-TraceID`	Consumer’s TraceID - a unique identifier provided by the consumer (i.e. GUID/UUID).
`Ssp-From`	Consumer’s ASID - a unique identifier for the consuming system. The consumer will be given an ASID by NHS Digital when connecting to the Spine.
`Ssp-To`	Provider’s ASID. Consumers MUST include the provider ASID in the `Ssp-To` HTTP header when performing a retrieval request via the SSP. The provider ASID can be obtained through performing a Spine Directory Services (SDS) lookup. This can be done using the Information Owner ODS code, which is included in the pointer metadata, and the interaction ID `urn:nhs:names:services:nrl:DocumentReference.content`. A worked example of the endpoint look-up process can be found in the Spine Core specification. If multiple ASIDs are found for the ODS code and interaction ID, the associated FQDN can be matched to the record URL FQDN to obtain the correct ASID.
`Ssp-InteractionID`	Spine’s Interaction ID. The interaction ID for retrieving a record referenced in an NRL pointer is a fixed value, specific to the NRL service: `urn:nhs:names:services:nrl:DocumentReference.content.read`

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:

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.
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.
All interactions with the SSP MUST be over port 443.
Endpoints MUST NOT include explicit port declarations (e.g. :443).
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:

GET https://[supplier_base_url]/[information_owner_ODS_code]/[path_to_record]

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:

For requests to providers	For responses from providers
ASID HTTP Request URL NHS Number ODS Code Pointer Logical ID Request Datetime Trace ID User ID	HTTP Response Body (if the request failed) HTTP Status Code Response Datetime

Provider Document/Record Retrieval

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

For requests from consumers
ASID HTTP Request URL HTTP Status Code ODS Code Record version or equivalent Request Datetime Trace ID User ID

Audit Log Attributes

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

Attribute	Source
ASID	`requesting_system` from JWT (only the ASID portion is required, for example, `https://fhir.nhs.uk/Id/accredited-system\\|[ASID]`).
HTTP Request URL	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	Response message.
HTTP Status Code	Describes the response outcome (Success: 2xx \| Fail: 4xx or 5xx).
NHS Number	This is the value used as part of the pointer subject reference (for example, `https://demographics.spineservices.nhs.uk/STU3/Patient/[nhsNumber]`) which may be an attribute on the pointer or a search query parameter depending on the action being performed.
ODS Code	`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.
Record version or equivalent	Reference to the version of the document (or equivalent) from which the NRL provider can identity what version of a record was provided.
Request Datetime	Datetime that audit log was written.
Response Datetime	Datetime that the response was received from NHS Digital 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	`requesting_user` from JWT

Tags: