With NHS CIS2 Authentication, 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 a system that has integrated with NHS CIS2 Authentication) 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.
For full details on how to do this, see parts 6 and 7 of the Spine External Interface Specification.
Here's a summary:
- Call the Identity Agent Ticket API to get the ID token for the healthcare worker's session.
- Call the Identity Server to get an SSO Token.
- Call the Identity Server to get the SAML Assertion.
- 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:
- Find the Job Role Profile block in the SAML assertion where the uniqueIdentifier field record matches the above ssbSessionRoleUid.
- Get the nhsJobRoleCode field from the same Job Role Profile, for example S0030:G0100:R0570.
- Check this against the roles and activities in the national RBAC database.
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.
2. Standards-compliant approach
You can get a full list of the healthcare worker's roles from NHS CIS2's authentication server, and present them to the healthcare worker to select a role. If the healthcare worker only has one role, you can select it for them automatically.
This approach uses open standards - OAuth 2.0 and Open ID Connect - and works 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 NHS CIS2's /userinfo endpoint. For more details on NHS CIS2 environments, see NHS Care Identity Service 2 path to live process.
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.
NHS CIS 2 uses standard OpenID Connect scopes to manage what information is available when you call the NHS CIS2’s /userinfo endpoint. To get a list of roles you must include the scope nationalrbacaccess. For a full list of claims returned by NHS CIS2, see Scopes and Claims.
You will receive a response with a JSON response body, containing at least the following fields:
||A 12-digit identifier uniquely identifying the healthcare worker and is commonly referred to as 'SDS User ID'
||The healthcare worker's full name.
||An array of the healthcare worker's registered roles
Each of the entries in nhsid_nrbac_roles contains at least the following fields:
||The organisation's ODS code
||A 12-digit identifier that uniquely identifies the healthcare worker's association with the organisation
||A 12-digit identifier that uniquely identifies the healthcare worker's role at the organisation. This is commonly referred to as 'SDS Role Profile ID'
||A colon-separated string of codes comprising a Primary, Secondary and Tertiary Job Role Code. This is commonly referred to as 'SDS Job Role Code'
||A colon-separated string of names comprising a Primary, Secondary and Tertiary Job Role Name
Here's an example: