10. Role selection

The purpose of this section is to describe how Relying Parties that need to make use of national role-based access control (RBAC) within their application (for example to access Spine APIs) can use the capabilities of NHS CIS2 Authentication to enable users to select and change their role.

There are three methods that a Relying Party can use to enable a user to select a role:

HSCN Identity Agent

The existing HSCN based Identity Agent will prompt the user to select a role when they first insert their smartcard and enter their PIN as illustrated below:

Details of the selected role can be obtained by the Relying Party by inspecting the selected_roleid claim in the ID Token returned following a successful authentication. For more details see the description of the ID Token in the Token Request section.

The following should be noted when using this method:

1. This method depends on all users of an application using a smartcard in combination with the HSCN Identity Agent. However NHS CIS2 Authentication offers a number of alternative authenticators, if such an alternative is used then the selected_roleid claim will not be populated.
2. The role is selected when the user initially inserts their smartcard and enters their PIN. There is no mechanism for a user to subsequently change their role without removing their smartcard which will terminate existing application sessions.
3. If the user only has a single role then the dialog will not be displayed and the selected_roleid claim will be automatically populated.
4. By default it is not possible for a user to authenticate with the HSCN Identity Agent without having at least one role. 

Note: Unlike the HSCN Identity Agent above, the new Internet Identity Agent will not present the user with a role selection screen and the Relying Party will need to provide the selectedrole scope to trigger the role selection dialog box as described below. This is the same behaviour as for other non-smartcard authenticators.

Relying Party Implementation

A Relying Party may chose to implement its own role selection screen using the user's RBAC information returned from the UserInfo endpoint. This RBAC information can be obtained by specifying the nationalrbacaccess scope in the authentication request and inspecting the nhsid_nrbac_roles JSON array returned in the UserInfo response as described in the Scopes and Claims section.

Relying Parties may decide to use this method if they wish to enrich the role selection process with additional information of their own e.g. by providing additional information on what a given role will permit the user to do within the application.

The following should be noted when using this method:

1. The HSCN Identity Agent always presents a role selection screen if a user has more than one role, therefore a user authenticating with a smartcard may see two role selection screens. This can be prevented if the application checks for the presence of the selected_roleid before presenting their screen.
2. A Relying Party may use a similar method to allow the user to change their role. This may entail an application storing the  nhsid_nrbac_roles data within the user session.
3. It is possible for an authenticated user to have many hundreds of roles. Any design should cater for this eventuality.
4. It is possible for an authenticated user to have no roles. Any design should cater for this eventuality.

Selected Role Scope

Release 6.01 of NHS CIS2 Authentication introduced a new capability addressed at overcoming both the disadvantages of relying on the HSCN identity Agent for role selection and the costs of a Relying Party having to implement their own solution.

A Relying Party can request that NHS CIS2 Authentication performs a role selection as part of the authentication by specifying the selectedrole scope in the initial authentication request e.g. 

Using this scope will result in the user being asked to select a role either via the existing HSCN Identity Agent role selection dialog or, for other authentication mechanisms, via a screen displayed directly after successful authentication. As for the HSCN Identity Agent solution described above details of the selected role can be obtained by inspecting the selected_roleid claim in the returned ID Token as detailed in the Token Request section.

The form of the role selection screen displayed depends on the number of roles that a user has. For five or fewer roles then a page will be displayed listing all the roles and user may select one by clicking anywhere on the panel containing the role. This is depicted below:

If the user has more than five roles then all the roles will still be listed but a search field is provided to allow the user to more readily find the correct one. This field allows the user to search within both the organisation and role name, the screenshot below shows a user who has searched for roles in the Y51 organisation.

The following should be noted when using this method:

1. This method has been designed to work with all authentication mechanisms including the HSCN identity Agent. To avoid the issue of  the user being prompted to select a role twice the role selection screen will not be displayed when the HSCN Identity Agent is used and instead the role selected via the dialog box will be returned in the ID Token.
2. To cater for the scenario where an application wants the user to choose a new role (or select one other than that selected via the HSCN Identity Agent) a changedrole scope is available as described in the section below.
3. In order for the role selection screen to be presented an authentication must occur, for this reason Relying Parties should use the selectedrole scope in conjunction with the prompt=login parameter (see the Prompt Parameter section for further details).
4. If the user only has a single role then no selection screen will be displayed and the selected_roleid claim will be automatically populated.
5. It is possible for an authenticated user to have no roles. Any application using this method should cater for this eventuality, this may mean not granting the user access.
6. To make use of this capability iPad users need to be using release 1.6.0 of the NHS CIS2 iOS App or above.

A Relying Party may wish to ask the authenticated user to change their role, for example to elevate their privilege within the application. As described above this is not possible if relying on the HSCN Identity Agent to select the user's role (as it will result in the user being logged out out of all applications) and so requires the Relying Party to implement their own role selection screen.

The changedrole scope introduced in Release 6.01 of NHS CIS2 Authentication provides a mechanism by which a Relying Party may request CIA to display a change role screen on behalf of the Relying Party. To use this mechanism the Relying Party should specify the changedrole scope in an authentication request e.g.

This will cause the user to be reauthenticated, after which a role selection screen will be displayed as described above. As for the selectedrole scope details of the selected role can be obtained by inspecting the selected_roleid claim in the returned ID Token as detailed in the Token Request section.

The following should be noted when using this method:

1. Using the changedrole scope will result in the role selection screen being displayed even if the user was originally authenticated using the HSCN Identity Agent. In this manner this method can be used to change the role of a user even when authenticated via the HSCN Identity Agent.
2. In order for the role selection screen to be presented an authentication must occur, for this reason Relying Parties should use the changedrole scope in conjunction with the prompt=login parameter (see the Prompt Parameter section for further details); max_age=0 will achieve the same. Otherwise, the role selected in a previous authentication journey will be presented. 
3. This mechanism assumes that the user has previously been authenticated. When using it the Relying Party MUST validate that the sub claim in the returned ID Token matches that of the existing user session.
4. Although this mechanism imposes a slight user experience overhead by requiring the user to reauthenticate it has the advantage of ensuring that any elevation of privilege requires the user to actually be present.
5. If the user only has a single role then no selection screen will be displayed and the selected_roleid claim will be automatically populated.
6. It is possible for an authenticated user to have no roles. Any application using this method should cater for this eventuality, this may mean not granting the user access.
7. To make use of this capability iPad users need to be using release 1.6.0 of the NHS CIS2 iOS App or above.

1. Registration
2. Discovery
3. Authorization code flow
4. Scopes and claims
5. ACR and AMR values
6. Signatures
7. Key management
8. Security considerations
9. Session management
10. Role selection