Spine Directory Service (SDS) guidance for developers

This guide provides an overview of the Spine Directory Service (SDS). It further explains Spine accredited systems and how to consume Spine services. 

The Spine Directory Service gives access to:

• NHS organisations, their sites and departments 
• people - healthcare workers who are Spine users, including their organisation and role
• systems registered with Spine

For a detailed formal specification, see the Spine External Interface Specification (EIS) Part 5 - Spine Directory Services (SDS).

Directory structure

The Spine Directory is a simple Lightweight Directory Access Protocol (LDAP) directory with the following basic structure:

• O=nhs
  • ou=Organisations
  • ou=People
  • ou=Services
  • ou=ReferenceData
  • ou=ChangeLog

The information contained in each branch is:

Organisations branch

Data about the organisational structure of the NHS - taken from the Organisation Data Service (note, these are the “legal” organisations rather than business services available to patients). The directory on Spine contains the following types of organisation entity:

• ou=Organisations
  • Organisation (nhsOrg)
  • Organisation Site
  • Department

Typically, consumers are likely to find it easier to consume organisation data from the ODS FHIR API.

People branch

The People branch contains data about all the healthcare workers who are users of the Spine. This data is confirmed by the Registration Authority during the user registration process and issuance of the user’s smartcard. The structure of the People branch is as follows:

• ou=People
  • Person (nhsPerson)
    • Organisational Person (nhsOrgPerson)
      • Role Profile (nhsOrgPersonRole)

Each Spine user has one entry immediately beneath the people branch. This entry contains all the data that is independent of an organisation e.g. first and family names.

Immediately beneath a person entry are organisational person entries associated with the user’s specific organisation data e.g. organisation name. A user may have multiple organisational person entries, one for each organisation with which they have a direct association.

Located beneath each specific organisational person entry are entries for each role profile that a user holds within the organisation. These role profile entries contain details of the job role, area of work, work groups and business functions associated with that role profile.

Services branch

The Services branch contains data about Accredited Systems and Message Handling Systems registered with the Spine. The structure of the Services branch is as follows:

• ou=Services
  • Accredited System (nhsAs)
  • Message Handling System (nhsMhs)

The accredited system entry type contains all the information related to a specific system:

• the accredited system identifier
• the party key of the Message Handling System to which messages for the accredited system should be sent
• the service-interactions the system supports, including versions

The message handling system entry type contains all the information related to a specific service-interaction supported by the system:

• the party key of the message handling system
• the version of the service-interaction the system supports
• the end-point bindings
• the interaction contract properties

ReferenceData branch

The ReferenceData branch contains five sub-branches:

• ou=ReferenceData
  • Types
  • Sub‑Types
  • Category Bags
  • Role Base Access Control entries
  • Work Groups
  • Work Group Types

The Types and Sub-Types contain types of Organisations, Sites and Departments referenced in the Organisation branch. Typically consumers will find it simpler to use the ODS FHIR API for this.

Category Bags are not typically used for FHIR APIs.

Role Base Access Control entries contain the national “baseline” RBAC roles and the business activities associated with each role. Each baseline entry includes:

• Baseline Code
• Job Role Code and Name
• a list of Area of Work Codes and Names
• a list of Business Function codes
• DN of the URP (User Role Profile) that created the baseline
• Creation Date

Work Groups and Work Group Types were used by the national Legitimate Relationship service, but are not typically used for FHIR APIs.

ChangeLog branch

Change Log entries are used to allow external directories to be synchronised with changes made to the Spine Directory.

SDS allows details of registered system endpoints to be looked up.

Spine accredited systems and endpoints

Every system that connects to the Spine has one or more “Accredited System” entries in the Spine Directory, 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.

In addition, each endpoint that is registered with the Spine has one or more “interaction IDs” associated with the endpoint. These identify the types of Spine interaction that the endpoint has been assured to perform. These are used to control what functionality can be called by connecting systems - calls to interactions for which the accredited system has not been assured will be blocked.

Terminology

Consuming Spine services

A consuming system will interact with SDS in order to resolve the FHIR Endpoint Server Root URL to be used when constructing the request to be made to the Spine service it wishes to call (or another external endpoint when sending a brokered call through the Spine Secure Proxy).

This is a two step process, as follows:

1. Lookup the Accredited System ID (ASID).
2. Lookup the Message Handling System (MHS).

Once the MHS record has been retrieved the fully qualified domain name (FQDN) and full endpoint of the FHIR server can be retrieved from returned attributes of the MHS record.

Systems should cache SDS query results giving details of the consuming system, endpoints and endpoint capability on a per session basis.

Consuming systems shall 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 consuming system, endpoint and endpoint capability.

Step 1a: Accredited System ID (ASID) lookup for a national Spine service

When the client wants to make a call to a national Spine service (for example NRLS, Visitors and Migrants), the first step is to establish the Party Key for the Spine (there is a single Party Key for each Spine environment. This is fixed for each environment, so does not need to be looked up on SDS - to find the Party Key for the Spine environment refers to the “Authority Service Names” document for the relevant Spine environment - see Environments for details.

Step 1b: Accredited System ID (ASID) lookup for an external service (brokered via SSP)

When the client wants to query an external service brokered through the Spine Security Proxy (e.g. a GP Connect API), the client SHALL use an organisation ODS code for the target organisation to lookup the Accredited System ID (ASID) as follows:

• Accredited System type
  • objectClass = nhsAs
• Organisational code
  • nhsIDCode = [odsCode] of the target organisation (for example, GP practice)
• Interaction ID
  • nhsAsSvcIA = [interactionId] of the API operation required

ldapsearch -x -H ldaps://ldap.vn03.national.ncrs.nhs.uk –b "ou=services, o=nhs" "(&(nhsIDCode=[odsCode]) (objectClass=nhsAS)(nhsAsSvcIA=[interactionId]))" uniqueIdentifier nhsMhsPartyKey

The ASID will be returned in the uniqueIdentifier attribute which is returned from the ldaps query above.

Note that ldaps is used to establish a TLS session rather than the StartTLS option. Also note that once the TLS session is established, SASL authentication is not used by SDS and is therefore disabled through the -x option.

Please refer to the specification of the specific FHIR API you are using for details of the interaction ID to use:

• GP Connect - Interaction IDs for details appropriate for your use case

Step 2: Message Handling System (MHS) lookup

Clients shall lookup the endpoint URL from the MHS record using the Party Key retrieved in step 1, as follows:

• Message Handling System type
  • objectClass = nhsMHS
• MHS Party Key
  • nhsMHSPartyKey = [partyKey] as retrieved from the nhsMhsPartyKey attribute in step 1
• MHS Interaction ID
  • nhsMhsSvcIA = [interactionId] of the API operation required(?)

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

The FHIR endpoint URL of the message handling system can then be extracted from the nhsMhsEndPoint attribute of the MHS record. The attribute nhsMhsFQDN could also be retrieved in the above query to retrieve the FQDN of the endpoint, though this can be extracted from the nhsMhsEndPoint.

ldapsearch 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 are available from Assurance Support.
2. Obtain a client certificate by submitting a certificate signing request for your development endpoint to Assurance Support.

Server certificate setup

For the examples above, ldapsearch should be configured to find the RootCA and SubCA certificates using the TLS_CACERT option in the ldap.conf file. This should point to a file, in PEM format, which contains both RootCA and SubCA certificates ensuring that the root certificate is placed after the SubCA certificate. The LDAPCONF environment variable can be used to define the location of the ldap.conf.

Client certificate setup

The client certificate and encrypted private key should be defined in the .ldaprc file using the following directives.

TLS_CERT C:\mydir\cert.pem TLS_KEY C:\mydir\key.pem

The location of the .ldaprc file can be defined using the LDAPRC environment variable.

See Environments for details of where to find URLs for SDS.

This is a worked example of looking up a Spine endpoint from SDS for calls brokered through SSP.

Worked example of the endpoint lookup process

Given A consuming system which needs to get the HTML View 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. Accredited system lookup on SDS

The ASID and Party Key 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)(nhsAsSvcIA=urn:nhs:names:services:gpconnect:fhir:operation:gpc.getcarerecord))" uniqueIdentifier nhsMhsPartyKey

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

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

Using the Party Key retrieved from Step 1, and the same interaction ID, the following ldapsearch query is executed:

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

nhsMhsEndPoint nhsMHSFQDN

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

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://[URL of Spine Security Proxy]/[Provider Server Root URL]/[FHIR request]

The value returned in the nhsMhsEndPoint attribute in Step 2 should be treated as the FHIR Server Root URL at the provider system.

In this example, to issue a GetCareRecord request, the following request would be made:

POST https://testspineproxy.nhs.domain.uk/https://pcs.thirdparty.nhs.uk/T99999/DSTU2/1/Patient/$gpc.getcarerecord

Provider system viewpoint

Please refer to Registering provider endpoints for details of requirements for systems wanting to register an API endpoint for consumers to call through the SSP.

This is a worked example of looking up a Spine endpoint from SDS for Spine FHIR APIs.

Worked example of the endpoint lookup process

Step 0. PDS Trace (pre-requisite step)

The Consuming system is responsible for performing a PDS Trace to verify the identity of the patient and find or confirm their NHS Number.

For this example, NHS Number 9000000084 with demographic details Mr Anthony Tester, 19 Fictitious Avenue, Testtown.

Step 1. Accredited system lookup on SDS

Assuming we are using the Spine Development environment, we can refer to the details of that environment and use the fixed party key value: YES-0000806.

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

We need to identify the interaction ID appropriate for the API call we wish to make. Assuming we are calling the Visitors and Migrants API and want to use major version 1 of that API, the interaction ID we need (as per the API spec for the API) is: urn:nhs:names:services:visitorsandmigrants:fhir:rest:search:observation:1.

Using the Party Key identified in Step 1, and the interaction ID, the following ldapsearch query is executed against the SDS URL for the appropriate environment:

ldapsearch -x -H ldaps://ldap.vn03.national.ncrs.nhs.uk -b "ou=services, o=nhs" "(&(nhsMhsPartyKey=YES-0000806) (objectClass=nhsMhs) (nhsMhsSvcIA=urn:nhs:names:services:visitorsandmigrants:fhir:rest:search:observation:1))" nhsMhsEndPoint nhsMHSFQDN

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

For more details, contact us.