National role-based access control (RBAC) for developers

Some of our APIs require you to implement national role-based access control (RBAC) in your software.

You can also choose to use national RBAC if you're using Care Identity Service (CIS) to authenticate health or social care workers. This would save you from having to build your own authorisation framework.

This page explains what national RBAC is and how to implement it.

Role-based access control (RBAC) is a way of ensuring that users are suitably authorised to perform specific actions in software applications.

Here's how it works:

1. users are assigned pre-defined roles - for example, Sarah is a general practitioner
2. roles are linked to pre-defined activities - for example, general practitioners can view patients' demographic details
3. users can have multiple roles - for example, Sarah might be both a general practitioner and a privacy officer
4. roles can be linked to multiple activities - for example, a general practitioner might be able to both view and amend patients' demographic details

We own and maintain a national database of roles and permissions for healthcare workers called the national RBAC database.

The database consists of:

• Job Roles (‘R’ codes) - the set of roles that can be assigned to users, for example Clinical Practitioner (R8000)

• Activities (‘B’ codes) - the set of activities that users can perform, for example Amend Patient Demographics (B0825)

• Baseline Policy - the default mapping of roles to activities, for example a Clinical Practitioner (R8000) can perform the Amend Patient Demographics (B0825) activity

Included activities

As part of the Baseline Policy, activities can include other activities. For example, Amend Patient Demographics (B0825) includes View Patient Demographics (B0820). When determining the activities for a given job role, you must also consider any included activities.

Accessing the national RBAC database

To access the national RBAC database, you can:

• access it directly in the Spine Directory Service (SDS) using the Spine Directory Service LDAP API

• download a snapshot of it as a spreadsheet

The database doesn’t change that often, so using a snapshot is fine in most cases.

User accounts and roles

To use national RBAC, users must:

• be registered with an account in the Care Identity Service (CIS)

• be assigned an appropriate role or roles from the national RBAC database

This is done by their Registration Authority (RA). The RA then issues the user with an authenticator - a smartcard and PIN or a modern alternative.

Role profiles and directly assigned activities

When a user is assigned a role, CIS creates a 'role profile'. This includes:

• The user to whom the profile applies
• The organisation to which the profile applies
• The role assigned to the user (from which their allowed activities can be inferred as per the Baseline Policy)
• Any other activities assigned directly to the user (see below)

Directly assigned activities

Normally, users are assigned roles, and roles are associated with activities according to the Baseline Policy, as explained above. Everyone with a given role can perform all the activities for that role, including the 'included' activities.

However, it is also possible to assign activities directly to a user's role profile.

In particular, this approach must be used for the e-Referral Service (e-RS), which has activities but no associated roles.

Therefore, when determining the full set of activities for a given role profile, you need to consider:

1. the activities that apply to a role, as per Baseline Policy
2. any 'included' activities, also as per the Baseline Policy
3. any directly assigned activities included in the role profile

If you’re using national RBAC solely to restrict access to specific functions within your application, and not to access our national APIs, the following steps apply:

1. allow the user to authenticate

2. allow the user to select a role for the current session - if they have multiple roles

3. check that the user is authorised for the activity they want to perform

Selecting a role

To allow a user to select, or change, their role, see Role selection.

The outcome of this step is to receive the selected role in the selected_roleid claim in the ID token.

Checking the user is authorised

To do this:

1. Get the nhsid_nrbac_roles claim from the ID token. This will only be present if you specified the nationalrbacaccess scope in your authentication request.
2. Find the object in the array where person_roleid matches selected_roleid. This is the selected role profile.
3. Find the role code for the selected role profile. This is in the role_code attribute, and you need to extract the ‘R’ code (it’s after the second colon).
4. Use the national RBAC database to look up the activities (‘B’ codes) associated with the role code.
5. Also include any 'included' activities. Note that included activities are recursive, so if R1000 includes R2000 and R2000 includes R3000, you need to include all three as allowed activities.
6. Also include any directly assigned activities. These are in the activity_codes array.
7. Check if the user has the activity code required for the function they wish to perform. Meanings for the activity codes are given in the national RBAC database.

If you’re implementing national RBAC to access one of our APIs, the approach depends on which API you’re using.

For most of our RESTful APIs, see the appropriate guidance for:

• combined authentication and authorisation
• separate authentication and authorisation

The e-Referral Service FHIR API has its own particular approach.