Search loading...

API Hub

Explore and Make use of Nationally Defined Messaging APIs

 


Overview and querying

Overview of the role of the Spine Directory Services (SDS) within GP Connect

Overview

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 in order to enable:

  • Consumer systems to lookup provider system’s 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.

MHS records and endpoints

Every GP Connect system also has one or more “MHS” records (or message handling server 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.

Please see System topologies for more details on the allocation of ASIDs and Party Keys.

Querying SDS

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 Spine Directory Service (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.

  • 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

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, in order 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

Worked example - 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 (pre-requisite 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

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.

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 TLS configuration

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 also 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

Looking up a consumer’s own ASID

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.

In order to ensure the right AS record and ASID is 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
  • 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

All content is available under the Open Government Licence v3.0, except where otherwise stated