Spine Directory Service

Spine Directory Service (SDS) is an endpoint and identifier directory for Spine and Spine connected systems, containing information on accredited systems, services and NHS registered users. It is accessed via the Lightweight Directory Access Protocol (LDAP).

GP Connect provider and consumer systems are registered in SDS to enable:

• consumer systems to lookup provider systems' ASID and endpoint information
• the Spine Secure Proxy to allow or deny requests based on known identifier and endpoint information

AS records

Every system that connects to the Spine has one or more Accredited System (AS) records in SDS, identified by an Accredited System Identifier (ASID).

This ASID is unique to a system deployed in a specific organisation, so the same application deployed into three NHS organisations would typically be represented as three unique ASIDs.

Message handling server (MHS) records and endpoints

Every GP Connect system also has one or more MHS record, identified by party key and interaction ID.

MHS records of GP Connect provider systems contain the endpoint of a capability at the target practice, as defined by the FHIR service root URL.

See System topologies for more details on the allocation of ASIDs and party keys.

Important: Distinguishing GP Connect provider and consumer SDS records
Providers have GP Connect interaction IDs on their MHS records; consumers do not. This distinction enables the SDS queries below to return the correct record, where a provider organisation has separate consumer systems in addition to their main provider system.

Looking up a provider’s endpoint and ASID

GP Connect consumer systems are expected to resolve the FHIR service root URL and ASID for a given capability at a GP provider organisation using SDS LDAP directory lookups.

This is a two step process, as follows:

1. Lookup the Message Handling System (MHS) record
2. Lookup the Accredited System (AS) record

The process allows a consumer system to retrieve the following details for a capability at a target GP provider organisation:

• FHIR service root URL, retrieved from the nhsMhsEndpoint element in step 1
• and the ASID, retrieved from uniqueIdentifier element in step 2

The FHIR service root URL is used to construct the full target URL for a GP Connect request. The provider’s ASID is sent in the Ssp-To HTTP header.

Please see below for more detail on the process.

Consumer systems:

• MUST NOT reuse the FHIR service root URL retrieved from SDS for an interaction in one GP Connect capability (such as Appointment Management) in another capability (such as Access Record Structured). The two capabilities will have different FHIR service root URLs.

  Important: Please note the FHIR service root URL (endpoint) returned for one capability may be different from that for another capability, for the same provider practice. Ensure you DO NOT re-use FHIR service root URLs (endpoints) between capabilities.

• SHOULD cache SDS query results giving details of provider system endpoints and endpoint capability on a per session basis.

• MUST NOT cache and re-use consuming system endpoint information derived from SDS across multiple patient encounters or practitioner usage sessions. Each new patient encounter will result in new lookups to ascertain the most up-to-date provider system endpoint and capability.

Step 1: Message Handling System (MHS) record lookup

Consumer systems MUST lookup the FHIR service root URL and party key from the MHS record, using the ODS code of the target practice and the GP Connect interaction ID, as follows:

Search criteria:

• Organisation code
  • nhsIDCode = ODS code of the target organisation (for example, GP practice)
• Message Handling System type
  • objectClass = nhsMHS
• MHS Interaction ID
  • nhsMhsSvcIA = Interaction ID, please see GP Connect interaction IDs

Result attributes:

• Target organisation’s FHIR service root URL
  • nhsMhsEndPoint
• Target organisation’s party key
  • nhsMhsPartyKey

ldapsearch query:

ldapsearch -x -H ldaps://ldap.vn03.national.ncrs.nhs.uk -b "ou=services, o=nhs" "(&(nhsidcode=[odsCode]) (objectClass=nhsMhs) (nhsMhsSvcIA=[interactionId]))" nhsMhsEndPoint nhsMhsPartyKey

Step 2: Accredited System record lookup

Consumer systems MUST use the party key retrieved in Step 1 along with the practice’s ODS code, to determine the ASID of the target practice, as follows:

Search criteria:

• Organisational code
  • nhsIDCode = ODS code of the target organisation (for example, GP practice)
• Accredited system type
  • objectClass = nhsAs
• MHS party key
  • nhsMHSPartyKey = Target organisation’s party key as retrieved from the nhsMhsPartyKey attribute in step 1

Result attributes:

• Target organisation’s ASID
  • uniqueIdentifier

ldapsearch query:

ldapsearch -x -H ldaps://ldap.vn03.national.ncrs.nhs.uk –b "ou=services, o=nhs" "(&(nhsidcode=[odsCode]) (objectclass=nhsAs) (nhsMHSPartyKey=[nhsMHSPartyKey]))" uniqueIdentifier

Looking up a provider’s endpoint and ASID

Given A consuming system which needs to get the structured record of a patient record at the patient’s registered practice. The consuming system has the following information about the patient:

• NHS number
• a set of demographic details about the patient

When the consuming system interacts with GP Connect

Then the following steps MUST be followed:

Step 0: PDS trace (prerequisite step)

The consuming system is responsible for performing a PDS trace to both verify the identity of the patient and retrieve the ODS code of the patient’s registered primary care practice.

For this example, NHS number 9000000084 with demographic details Mr Anthony Tester, 19 Fictitious Avenue, Testtown returns the ODS code T99999.

Step 1: MHS record lookup on SDS to determine FHIR endpoint server root URL

Using the ODS code retrieved from Step 0, and the interaction ID of the required service, the following ldapsearch query is executed:

ldapsearch -x -H ldaps://ldap.vn03.national.ncrs.nhs.uk -b "ou=services, o=nhs" "(&(nhsIDCode=T99999) (objectClass=nhsMhs) (nhsMhsSvcIA=urn:nhs:names:services:gpconnect:fhir:operation:gpc.getstructuredrecord-1))" nhsMhsEndPoint nhsMhsPartyKey

This query should return a single endpoint. In this case, the ldapquery returns the following results:

# 472b35d4641b76454b13, Services, nhs dn: uniqueIdentifier=472b35d4641b76454b13,ou=Services,o=nhs nhsMhsEndPoint: https://pcs.thirdparty.nhs.uk/T99999/STU3/1/gpconnect/structured nhsMhsPartyKey: T99999-9999999 # search result search: 1 result: 0 Success

Important: Please note the FHIR service root URL (endpoint) returned for one capability may be different from that for another capability, for the same practice. Please ensure you DO NOT re-use FHIR service root URLs (endpoints) between capabilities.

Step 2: AS record lookup on SDS to determine the provider’s ASID

The ASID is now looked up on SDS. The example below uses ldapsearch:

ldapsearch -x -H ldaps://ldap.vn03.national.ncrs.nhs.uk –b "ou=services, o=nhs" "(&(nhsIDCode=T99999) (objectClass=nhsAS) (nhsMHSPartyKey=T99999-9999999))" uniqueIdentifier

This query should return a single matching accredited system object from SDS, the ASID being found in the uniqueIdentifier attribute. In this case, the ldapquery returns the following results:

999999999999, Services, nhs dn: uniqueIdentifier=9999999999,ou=Services,o=nhs uniqueIdentifier: 999999999999
# search result
search: 1
result: 0 Success

Step 3: Consumer constructs full GP Connect request URL to be sent to the Spine Security Proxy

The format of the full URL which the consuming system is responsible for constructing is as follows:

https://[ssp_fqdn]/[provider_service_root_url]/[fhir_request]

The value returned in the nhsMhsEndPoint attribute in Step 1 should be treated as the [provider_service_root_url] at the provider system.

Important: The SSP will reject requests where the [provider_service_root_url] portion of the above URL does not match that held in SDS (in the nhsMhsEndPoint attribute). Consumer systems must take care not to amend this portion, for example replacing the domain name with an equivalent IP address, or adding an explicit :443 port declaration.

In this example, to issue a Get Structured Record request, the following request would be made:

POST https://testspineproxy.nhs.domain.uk/https://pcs.thirdparty.nhs.uk/T99999/STU3/1/gpconnect/structured/Patient/$gpc.getstructuredrecord

SDS requires TLS Mutual Authentication. It is therefore necessary to configure ldapsearch in the examples above with the certificates necessary to verify the authenticity of the SDS LDAP server, and to enable SDS to verify the Spine endpoint making the LDAP request:

1. Root and SubCA Spine development certificates available from Assurance Support.
2. Obtain a client certificate by submitting a certificate signing request for your development endpoint to Assurance Support.

Important: This LDAP query is for a consumer system to lookup their own ASID. To determine the provider’s ASID and endpoint, see the queries above.

A consumer is required to populate their ASID in the Ssp-From HTTP header when sending a GP Connect request.

Consumer systems deployed at many sites may prefer to dynamically query their own ASID instead of holding as local configuration.

Consumer system suppliers wishing to do this should be aware that there may be more than one GP Connect consumer system deployed at an organisation, and hence multiple AS records for a given ODS code.

To ensure the correct AS record and ASID are retrieved, an additional search field should be used - nhsMhsManufacturerOrg is recommended - which will filter out AS records from other suppliers.

AS record lookup on SDS to determine the consumer’s ASID.

Search criteria:

• Organisational code
  • nhsIDCode = ODS code of the consumer organisation
• Accredited System type
  • objectClass = nhsAs
• AS Interaction ID
  • nhsAsSvcIA = Interaction ID, please see GP Connect interaction IDs 
• Manufacturer of the consumer system (the ODS code of the manufacturer of the consumer system)
  • nhsMhsManufacturerOrg = ODS code of the consumer system supplier

Result attributes:

• Consumer’s ASID
  • uniqueIdentifier

ldapsearch query:

ldapsearch -x -H ldaps://ldap.vn03.national.ncrs.nhs.uk –b "ou=services, o=nhs"

"(&(nhsIDCode=[odsCode]) (objectClass=nhsAS) (nhsaASvcIA=[interactionId]) (nhsMhsManufacturerOrg=[odsCode]))"

uniqueIdentifier

1. Common SDS requirements

1.1 Unique ASID per organisation using a system

Every system using GP Connect SHALL have a unique ASID for each organisation using it, so the same system deployed into three organisations would be represented by three unique ASIDs.

Conversely, if two different consumer systems are deployed in a single organisation, two unique ASIDs would be required.

Shared systems such as a Regional portal which are provisioned by a single organisation, but used by other organisations, SHALL have a unique ASID per organisation using the system.

Note: When sending GP Connect requests, the ASID of the organisation making the GP Connect request SHALL be sent in the Ssp-From header to ensure the true ‘originator’ of the request is properly declared. Shared systems SHALL NOT send the provisioning organisation’s ASID.

1.2 Do not reuse GP Connect ASIDs and party keys for central Spine services

New GP Connect ASIDs and party keys must be registered for use with GP Connect; existing ASIDs and party keys for central Spine services SHALL NOT be reused.

1.3 Maximum of one GP Connect provider system per organisation

Only one GP Connect provider system can be registered in SDS for an organisation; multiple provider systems for the same organisation are NOT supported.

1.4 Multiple GP Connect consumer systems per organisation to be supported

Only one consumer system per organisation is supported currently. However, once all providers and consumers have migrated to version 1.2.3 of the GP Connect API specification - specifically uplifting their SDS queries - more than one will be supported.

Examples:

• an urgent care centre with an Access Record HTML consumer system, and a separate Appointments consumer system
• a GP practice using a GP system with GP Connect enabled as provider and consumer, and a separate regional portal system with access to Access Record HTML as a consumer

Important: Distinguishing provider and consumer SDS records
Providers have GP Connect interaction IDs on their SDS MHS record; consumers do not. This distinction enables the SDS queries to look up a GP Connect provider endpoint to function correctly.

2. Consumer specific SDS requirements

Important: If a system is both a consumer and provider (for example, a GP principal system), please refer to 'Provider specific SDS requirements' below instead.

2.1 Use separate MHS and AS endpoint records; not CMA style endpoints

Consumers MUST NOT register entries in SDS as CMA (combined MHS and AS) style endpoints. This is because the MHS record for a consumer system MUST NOT have GP Connect interactions on the endpoint, whereas the AS record MUST - creating a CMA style endpoint will not allow this distinction to be made.

2.2 GP Connect interaction IDs on AS records only

GP Connect interaction IDs on AS records indicate the system is permitted to send GP Connect messages as a consumer.

GP Connect interaction IDs on an MHS record indicate the message handling srver is a GP Connect provider. Therefore, this SHALL NOT be done for consumer (only) systems.

2.3 Shared party key may be used depending on topology

Consumer systems MAY use a single GP Connect party key for multiple organisations, if they connect to Spine via a single shared message handling server.

However, as described above in '1.1 Unique ASID per system used by an organisation' each consumer organisation SHALL have its own unique ASID.

Please see System topologies for more information.

3. Provider specific SDS requirements

Important: These requirements apply to provider systems, including those that offer provider and consumer functionality within the same system.

3.1 Use CMA type endpoints

To allow for practice specific routing using endpoints, all systems SHALL have a unique GP Connect party key and ASID per practice, registered in SDS as a 'CMA type' endpoint.

A CMA type endpoint refers to an endpoint which is a combined MHS system and accredited system endpoint. There will be a 1-1 mapping between an accredited system (uniquely identified by an ASID) record and an MHS record. A single MHS record SHALL be associated with a given ASID and interaction ID.

3.2 GP Connect Interaction IDs on MHS and AS records

GP Connect Interaction IDs SHALL be registered on both MHS and AS records (using a CMA type endpoint).

GP Connect interaction IDs on an MHS record indicate the Messaging Handling Server is a GP Connect provider.

3.3 Provider systems who are also consumers use the same ASID and party key for both roles

Provider systems which also offer consumer functionality SHALL use the same GP Connect party key and ASID for both provider and consumer roles.

3.4 Format of Service Root URL

The Service Root URL for a given ASID SHALL be defined in the nhsMhsEndPoint attribute of the MHS record (that is, the LDAP object of type nhsMhs). This URL SHALL be in the format described in Service Root URL versioning guidance.

As described in the API versioning guidance, the practice’s ODS code SHALL be placed in the FHIR server root URL, and this SHALL match the value in the nhsidcode elements on the MHS and associated AS records. ODS codes which refer to clinical systems as a single entity SHALL NOT be used to provide routing. Practice specific ODS codes SHALL be used for routing purposes in the FHIR Server Root URL found in the nhsMhsEndPoint attribute of the MHS record.

Important: Please note the FHIR service root URL (endpoint) for one GP Connect capability may be different from that for another capability, for the same provider practice and system. See the definition of the FHIR Service Root URL for more information.

3.5 nhsMhsEndPoint attribute SHALL contain the FHIR service root URL only

The nhsMhsEndPoint attribute in the MHS record SHALL contain the FHIR Service Root URL. It is the responsibility of the consuming system to construct the FHIR operation or RESTful resource request which will be postfixed to this base URL.

An example of a FHIR server root URL for a Retrieve a patient’s structured record interaction at practice GP0001 is:

https://provider.thirdparty.nhs.uk/GP0001/STU3/1/gpconnect/structured

Note that the /Patient/$gpc.getstructuredrecord is NOT added.

In line with this, provider systems SHOULD perform checks that the FHIR request received is a reasonable means to request the resource in view given the specified interaction.

3.6 FHIR service root URLs associated with a given product set SHALL use same FHIR version

Where a provider moves in future to a later version of FHIR, it will be necessary to define a new product set to accommodate the set of interactions provided by this. FHIR server root URLs defined for a specific product set SHALL all reference the same FHIR version. This ensures that FHIR resources references returned in FHIR responses are locally resolvable.

For example, all interactions associated with the Appointment Management capability pack in a given product set must refer to the same FHIR server, so that the resource references for ‘Read Appointment’ and ‘Amend’ appointment would be locally resolvable to the same resource on the same FHIR Server.

3.7 Acceptable use of ASID information in HTTP Headers

Source and destination ASID information is passed to the provider system from the Spine Security Proxy. Providers SHALL use this information for audit and debugging purposes only, and SHALL NOT use these headers to perform routing or lookups.

It is the responsibility of the SSP to perform lookups to determine consumer accreditation status. Routing shall be carried out as described above through practice-specific ODS codes present in the FHIR server root URL.