User-restricted RESTful APIs - NHS Care Identity Service 2 combined authentication and authorisation

This page explains how to integrate your software with our user-restricted RESTful APIs.

In particular, it describes the NHS Care Identity Service 2 (NHS CIS2) combined authentication and authorisation pattern, which uses our OAuth 2.0 authorisation server.

For a full list of available patterns, see Security and authorisation.

Use this pattern when:

• accessing a user-restricted RESTful API
• the end user is a healthcare worker
• you want a simpler integration
• you do not need the healthcare worker's identity information

In particular, this pattern is not appropriate when building GP software.

In this pattern, authentication and authorisation are done together. Authentication is done by NHS CIS2 Care Identity Authentication API but we co-ordinate that under the covers behind our OAuth2.0 authorisation server. Your application only needs to be registered with the API Platform, not NHS CIS2.

The healthcare worker authenticates with either an NHS smartcard or a more modern alternative. To use smartcards, you need to be connected to the Health and Social Care Network (HSCN).

The following diagram illustrates the pattern:

The following sequence diagram shows how the various components interact:

In words:

1. The healthcare worker launches the calling application.
2. The calling application redirects the healthcare worker's browser to our OAuth2.0 authorisation endpoint (/oauth2/authorize).
3. The healthcare worker signs in to their NHS CIS2 account (using a smartcard and PIN, or thumbprint reader, or other method).
4. Our authorisation server redirects control back to the calling application, with an authorisation code.
5. The calling application calls our OAuth2.0 token endpoint (/oauth2/token), with the authorisation code, and receives an access token in return.
6. Time passes, until the healthcare worker needs to access a user-restricted API.
7. The calling application calls the user-restricted API, including the access token.

If you are already using our original Care Identity Service (CIS) in your application, see Using CIS2 with CIS for API access.

You can learn how to use this security pattern with our tutorials written in:

• Java
• PHP
• C#

Bear in mind that the tutorial only teaches you the basic flow. You'll also need to read the detailed integration instructions below to understand how to handle error scenarios.

The following diagram shows the high level integration phases with the API platform and the sections below it explain in detail how to use this security pattern.

As well as production, we have a number of test environments. Each environment is paired with a suitable CIS2 environment. In the steps below, make sure you use the appropriate URL base path:

For more information on testing, see Testing APIs.

This section explains the detailed steps to set up your application before you can initiate authorisation. The steps involved are:

• register your application on the API platform
• trigger the authorisation journey
• healthcare worker completes authentication and authorisation
• receive authorisation results

To use this pattern, you need to register an application. This gives you access to your API Key and Secret, and allows you to specify your Callback URL, all of which you will need later in the process.

1. If you do not already have one, create a developer account.
2. Navigate to my developer account and sign in.
3. Select 'Environment access' on my developer account.
4. Select 'Add new application'.
5. Enter the details of your application including application owner and application name to create your new application.
6. Select 'View your new application' to check or edit your application details.
7. Click the 'Edit' button to make a note of the API key. If you are editing the security details for production applications, follow the online instructions to set up mobile authentication. 
8. Click the 'Add APIs' button to add the API you want to use.
9. Enter the Callback URL for your application. See step 4 for more details.

For the Hello World (Sandbox) example, you need to select the API "Hello World API - User Restricted (Sandbox)".

When you want to start authorisation, your software should launch a browser window, or redirect the current browser window to our OAuth 2.0 authorisation endpoint:

https://api.service.nhs.uk/oauth2/authorize

Note: the above URL is for our production environment. For other environments, see Environments and testing.

You need to include a number of parameters to make it work:

Here's an example redirect:

curl -X GET "https://api.service.nhs.uk/oauth2/authorize?\
response_type=code\
&client_id=ToabcdPayTQACdxyzJK1234nKUD0Ag7J\
&redirect_uri=https%3A%2F%2Fwww.example.com%2Fcallback\
&state=30de877c-ee2f-15db-8314-0800200c9a66"

Note: the URL in the above example is for our production environment. For other environments, see Environments and testing.

Error scenarios

If there is an issue with your call to our authorisation endpoint, we will return an error response to the healthcare worker's browser, as follows:

Authentication

Using the browser session your software triggered in step 2, the healthcare worker signs in to their NHS CIS2 account.

If they are using an NHS smartcard, they need the following:

• an HSCN connection
• a smartcard reader attached to their device
• the Identity Agent software installed on their device
• the NHS Credential Management software installed on their device

To see which versions of Windows operating systems and browsers are supported, see Supported operating systems and browsers.

To download Identity Agent and NHS Credential Management software over your HSCN connection, see guidance on setting up and troubleshooting.

If testing with our second generation mock authorisation service, enter the user ID for the test user you want to use.

If testing with our first generation mock authorisation service, simply click the 'sign in' button - you do not need any credentials.

Authorisation

Normally with OAuth 2.0, the end user is then required to grant authority to your software to act on their behalf. However, for healthcare workers using NHS APIs, we do not require the healthcare worker to explicitly grant authority, so all the healthcare worker needs to do is sign in.

Once the healthcare worker has completed authorisation, our authorisation server will redirect the healthcare worker's browser back to your software.

You need to provide a callback endpoint on your web server for this. If your software does not have a web server, you will need to create one. For alternative approaches, please contact us.

You need to tell us the location of your callback endpoint so we know where to redirect back to. This is the Callback URL you specified in step 1 above.

Your callback endpoint will need to expect the following query parameters:

We return state back to you so you can be sure the callback has come from us. For security reasons you should check the state we returned is the same as the state you sent.

Here's an example redirect after a successful authorisation:

// Example successful authorisation redirect
HTTP/1.1 302 Found
https://testapp.domain.com/callback?code=fXplvYDHxhSDTnYOYSgX4DM9sp0&state=30de877c-ee2f-15db-8314-0800200c9a66

This section explains the steps to get your application authorised before calling the user-restricted API. The steps involved are:

• exchange authorisation code for access token
• store access token for later use

Once you have an authorisation code, you need to call our token endpoint to exchange it for an access token. This is an HTTP POST to the following endpoint:

https://api.service.nhs.uk/oauth2/token

Note: the above URL is for our production environment. For other environments, see Environments and testing.

You need to include the following query parameters:

Here's a complete example, as a CURL command:

curl -X POST -H "content-type:application/x-www-form-urlencoded" --data \
"grant_type=authorization_code\
&client_id=[YOUR-API-KEY]\
&client_secret=[YOUR-SECRET]\
&redirect_uri=[YOUR-CALLBACK-URL]\
&code=[AUTHORIZATION-CODE]" \
https://api.service.nhs.uk/oauth2/token

Note: the URL in the above example is for our production environment. For other environments, see Environments and testing.

You will receive a response with a JSON response body, containing the following fields:

Here's an example:

{'access_token': 'Sr5PGv19wTEHJdDr2wx2f7IGd0cw',
 'expires_in': '599',
 'refresh_count': '0',
 'refresh_token': '7qvwCqqUUAmzMjRbQyrhdddwBQUJ9vmt',
 'refresh_token_expires_in': '35999',
 'token_type': 'Bearer'}

Error scenarios

If there are any issues with your call to our token endpoint, we return an error response, as follows:

Your access token lasts for 10 minutes and you can use it multiple times. If you'll be making more than one API call for this user, store your access token securely for later use.

This reduces the load on our authorisation server and also reduces the chance of your application hitting its rate limit.

For details on what to do if your access token has expired, see refresh token below.

This section explains the detailed activities that you need to perform to call a user-restricted API. The activities involved are:

• determine the healthcare worker's role
• call a user-restricted API
• refresh your access token
• request a new token from us

With NHS CIS2, healthcare workers are allocated one or more roles by their Registration Authority, for example Clinical Practitioner or Nurse.

Some of our APIs require you to send the healthcare worker's role when you call the API.

Some of our APIs also require you to implement national role-based access control (RBAC) within your software to ensure that the healthcare worker only has access to functions and information that are appropriate for their role.

If the healthcare worker has more than one role, they must select a role before using your software.

There are two ways to determine the healthcare worker's role:

1. Custom approach for smartcard users

If the healthcare worker signs in to their NHS CIS2 account with an NHS smartcard, the Identity Agent software on their device prompts them to select a role immediately after they sign in.

Healthcare workers with one role

If the healthcare worker has only one role, the Identity Agent automatically selects it for them. You do not need to send the role in the request header as the API retrieves it from the Identity Agent software on the healthcare worker's machine.

Healthcare workers with more than one role

If the healthcare worker has more than one role, they have to select one of them when prompted by Identity Agent software immediately after they sign in. You do not need to send the role in the request header, as the API retrieves it from the Identity Agent software on the healthcare worker's machine. However, if you need to override the selected role, you can send another role in the request header, which we then validate against the healthcare worker’s information.

To get the full list of the healthcare worker's roles, make an HTTP GET request to our /userinfo endpoint:

https://api.service.nhs.uk/oauth2/userinfo

To do this, you need the access token from step 5 above,

Error scenarios

If the healthcare worker's role validation is not successful, you get the following error messages when you call a user restricted API.  Follow steps 2 to 5, to avoid selected_roleid error message.

This is not a standards-compliant approach and does not work for other sign-in methods. If your software is already integrated directly with the Identity Agent, it might be appropriate to retrieve the selected healthcare worker role directly from NHS CIS2. 

For full details on how to do this, see parts 6 and 7 of the Spine External Interface Specification.

Here's a summary:

1. Call the Identity Agent Ticket API to get the ID token for the healthcare worker's session.
2. Call the Identity Server to get an SSO Token.
3. Call the Identity Server to get the SAML Assertion.
4. Get the ssbSessionRoleUid field from the Person block in the SAML assertion - this is the healthcare worker's selected User Role ID, for example 555021935107.

If the API also requires you to implement national RBAC:

1. Find the Job Role Profile block in the SAML assertion where the uniqueIdentifier field record matches the above ssbSessionRoleUid.
2. Get the nhsJobRoleCode field from the same Job Role Profile, for example S0030:G0100:R0570.
3. Check this against the roles and activities in the national RBAC database.

2. Standards-compliant approach

You can get a full list of the healthcare worker's roles from our authorisation server, and present them to the healthcare worker to select a role. If the healthcare worker has only one role, you can select it for them automatically.

This approach uses open standards - OAuth 2.0 and Open ID Connect - and will work for all types of authentication, not just smartcards.

If you take this approach, healthcare workers signing in with an NHS smartcard will actually be prompted to select a role twice - once by the Identity Agent and once by your software. Their first selection will be ignored.

To use this approach, make an HTTP GET request to our /userinfo endpoint:

https://api.service.nhs.uk/oauth2/userinfo

Note: the above URL is for our production environment. For other environments, see Environments and testing.

You need to include the following headers in your call:

• Authorization = Bearer <your access token from step 5>

Note: you should only call this endpoint within an hour of obtaining an access token. Requests made outside of this window will be rejected.

You will receive a response with a JSON response body, containing at least the following fields:

Each of the entries in nhsid_nrbac_roles contains at least the following fields:

Here's an example:

The response may include extra optional fields. For more details on the possible fields returned, see the national rbac access section of the NHS CIS2 specification.

Once you have an access token, you can call a user-restricted API.

You need to include the following headers in your call:

• Authorization = Bearer <your access token from step 5>
• NHSD-Session-URID  =  <healthcare worker role ID from step 7> (optional - not all APIs require this)

Here's an example, using a CURL command:

curl -X GET https://sandbox.api.service.nhs.uk/hello-world/hello/user \
-H "Authorization: Bearer [your access token from step 5]" \
-H "NHSD-Session-URID: [healthcare worker role ID from step 7]"

Note: the URL in the above example is for our sandbox environment. For other environments, see Environments and testing.

All being well, you’ll receive an appropriate response from the API, for example:

HTTP Status: 200
{
  "message": "Hello User!"
}

Error scenarios

If there is an issue with your access token, we will return an error response as follows:

For details of API-specific error conditions, see the relevant API specification in our API and integration catalogue.

Your access token expires after 10 minutes and must be refreshed.

If your access token has expired, when you call a user-restricted API, you receive a response with an HTTP status code of 401 (Unauthorized) and an error code of invalid_credentials.

To refresh the access token, submit the expired token's corresponding refresh token to our token endpoint using grant_type of refresh_token .

You can continue to request new access tokens for up to 12 hours.  When you refresh an access token, you get a new access token and it invalidates the original access token immediately. You also get issued a new refresh token to replace the one you just used.

Example request

curl -X POST -H "content-type: application/x-www-form-urlencoded" --data \
"client_secret=[YOUR-SECRET]\
&client_id=[YOUR-API-KEY]\
&grant_type=refresh_token\
&refresh_token=[REFRESH-TOKEN]" \
https://api.service.nhs.uk/oauth2/token

Note: the URL in the above example is for our production environment. For other environments, see Environments and testing.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{  
   "access_token": "xjPOKAmxlLXQcHkRkBf37AiaGyEx",
   "expires_in": "599",
   "refresh_token": "A6dpFV8F1yjsca4zPr5GDO0n7raSB6TQ",
   "refresh_token_expires_in": "43199", 
   "refresh_count": "1",
   "token_type": "Bearer"
}

Error scenarios  

You can continue to request new access_tokens for up to 12 hours.

After that, calls to our token endpoint return an HTTP status code of 400 (Bad Request) and an error code of invalid_request.

If this happens, you must send the healthcare worker back through the full authorisation process from step 2 above.

Note that NHS CIS2 session cookies last for 12 hours, so the healthcare worker does not need to re-authenticate. However, the system might check, for example, that their smartcard is still inserted.

If you use a smartcard to authenticate and then remove your smartcard from the reader, we revoke your access and refresh tokens using Back Channel Logout. This extra level of security ensures your tokens cannot be used if you are no longer present.

For details on how else to revoke an access token, contact us.