Migrating APIs from CIS1 to CIS2

This page explains a practical way to update your existing applications to use our more modern internet facing CIS2 Authentication alongside older APIs.  This guide focuses on existing APIs which are secured by CIS1 Authentication, for example PDS HL7 V3.

CIS2 Authentication is our strategic, internet facing service for healthcare worker authentication.

It works with NHS smartcards, but also provides a number of more modern alternatives, such as iPad authentication, Windows Hello and passkeys.

If you want to update your applications to this newer, more secure solution, you can split up the development work as follows:

1. Migrate to CIS2 Authentication first.
2. As a follow-on project, connect with our newer internet facing FHIR APIs, for example, the PDS FHIR API.

For guidance on how to onboard and integrate with CIS2 Authentication see CIS2 Authentication.

A two-step migration is possible because most older APIs are compatible with CIS2 Authentication.

For the compatible APIs, the switch from CIS1 to CIS2 is very limited in scope - your software only has to change to:

• use OpenID Connect (OIDC) to authenticate the end user
• obtain the end user data from CIS2 Authentication instead

Authentication metadata for user-restricted APIs originates from the Spine Directory Service (SDS), consisting of:

• details of the end user
• role IDs

Existing software obtains this data from CIS1. To update your software, you need to retrieve the same metadata from CIS2 Authentication and insert it in the same places.

The first place to look for CIS2 Authentication metadata is in the ID Token. This is a limited dataset, and in almost every case you will need to use additional scopes and call the userinfo endpoint to obtain all the metadata. 

We secure user-restricted APIs available on the private HSCN using two patterns:

• HL7 wrappers
• a JSON Web Token (JWT) designed to hold Spine authorisation and audit metadata

Both these patterns contain similar authorisation metadata.

The authorisation metadata is contained in the HL7 message format outside of the payload. You can find a summary of fields in the Spine External Interface Specification (EIS). For version 11.6, see Part 2 section 2.4.3.

This applies to the following APIs:

• Electronic Prescription Service - HL7 V3 
• Child Protection Information Sharing - HL7 V3
• Personal Demographics Service - HL7 V3
• Summary Care Record - HL7 V3
• Access Control Service - HL7 V3
• Alerts - HL7 V3
• Pathology Messaging - HL7 V3
• GP2GP - HL7 V3

When your software needs to call an API that requires a user to be present, the software must take the CIS authenticated user details and build a JSON Web Token (JWT). If you want to read how this was previously done (prior to CIS2 Authentication) you can read about it here: https://developer.nhs.uk/apis/spine-core-1-0/security_jwt.html

For the following APIs, at least one endpoint is secured using the Spine JWT, and user information is mandatory:

• National Record Locator - FHIR API
• National Events Management Service - FHIR API - user is optional, but if user authentication took place you should include it

User-restricted APIs that use the Spine Secure Proxy (SSP) are:

• GP Connect Access Document - FHIR API
• GP Connect Access Record: HTML - FHIR API
• GP Connect Access Record: Structured - FHIR API
• GP Connect Appointment Management - FHIR API

Some APIs and services are not compatible with CIS2 Authentication.

e-Referral Service has a number of APIs and, of the older ones, there is only one that is user restricted:

• e-Referral Service - FHIR API (HSCN)

This is not compatible with CIS2 as it requires the use of the CIS1 SSO token, which is not available in CIS2 Authentication. To use this API you establish a session with the 'Professional Session' endpoints (A001, A002 and A003), however, to call them you must retrieve the CIS1 SSO token by using getTicket(). (Note that we removed these endpoints in the internet facing version of the e-Referral Service - FHIR API.)

The only way move to authentication with CIS2 is to upgrade your software to use the new e-Referral Service - FHIR API and CIS2 Authentication at the same time.

For clarity, the e-Referral Service - HL7 V3 is only application restricted, so does not use CIS1.

This page only applies to user-restricted APIs, not application-restricted, for instance Spine Directory Service - LDAP API is only ever used as an application-restricted API.

The following user-restricted API uses the Spine JWT authorisation security pattern, but is only for internal NHS use:

• National Data Opt-out - FHIR API