Skip to main content

4. Scopes and claims

Page contents

Summary

OAuth 2.0 uses scope values to specify what access privileges are being requested for Access Tokens. The scopes associated with Access Tokens determine what resources will be available when they are used to access OAuth 2.0 protected endpoints. For OpenID Connect, scopes can be used to request that specific sets of information about the End-User be made available as Claim Values, which in the case of the NHS CIS2 Authentication OpenID Provider are made available via the UserInfo Endpoint. Multiple scope values MAY be used by creating a space delimited, case sensitive list of ASCII scope values as in the example below requesting the standard profile scope and the NHS Identity specific nationalrbacaccess scope (note the openid scope MUST be provided an OpenID Connect request).
The claims in the ID Token come as part of the openid scope

ASCII scope values for a standard profile

HTTP/1.1 302 Found
  Location: https://am.nhsdev.auth-ptl.cis2.spineservices.nhs.uk:443/openam/oauth2/realms/root/realms/oidc/authorize?
    response_type=code
    &scope=openid%20profile%20nationalrbacaccess
    &client_id=999999999999.apps.national
    &state=af0ifjsldkj
    &redirect_uri=https%3A%2F%2Fwww.nationalsupplier.nhs.net%2Fcallback

Scopes

Standard OIDC Scopes supported by the NHS CIS2 Authentication OpenID Provider.

Scope Description
profile This scope value requests access to the End-User's default profile Claims, which for NHS CIS2 Authentication are: name, family_name, given_name and uid.
email This scope value requests access to the End-User's email Claims, which for NHS CIS2 Authentication is email.

 

Extended Scopes supported by the NHS CIS2 Authentication OpenID Provider.

Scope Description
nhsperson Claims about the End-User's basic NHS profile.
associatedorgs Claims about the organisations the End-User has a role with.
nationalrbacaccess Claims about the National RBAC roles assigned to the End-User.
professionalmemberships Claims about the End-User's professional memberships.
organisationalmemberships Claims about the End-User's professional memberships in the context of a specific organisation. 
selectedrole Triggers a role selection after an authentication.
changedrole Triggers a change of role.

For more details of the use of the selectedrole and changedrole scopes see the Role Selection section.

Claims

This section gives more detail on the individual claims grouped by the scopes in which they occur. Most of the claims are derived from data held in the Spine Directory Service (SDS) and readers may find additional useful information in the section 5.5 of the SDS External Interface Specification.

Any Claims contained in the UserInfo Response other than those listed in the tables below MUST be ignored by the Relying Party.

profile

This is the standard OpenID Connect profile scope, NHS CIS2 Authentication supports the following claims:

Claim Description
name The End-User's full name using the format surname first name title e.g. Smith Jane Ms. Note entries created in SDS prior to 2015 may use other formats. 
family_name The End-User's surname.
given_name The End-User's first name.
uid A 12 digit identifier uniquely identifying the End-User within NHS CIS2 Authentication, such as 999999999999. This is the same value as used in the sub claim.

 

email

This is the standard OpenID Connect profile scope, NHS CIS2 Authentication supports the following claims:

Claim Description
email The End-User's contact email address. This value may have been entered by the End-User or by the Registration Authority who created their identity. The email address is not verified and it SHOULD NOT be assumed by Relying Parties that the End-User is in control of the email address.

 

nhsperson

This is the End-User's basic NHS profile scope:

Claim Description
nhsid_useruid A 12 digit identifier uniquely identifying the End-User within NHS CIS2 Authentication Identity e.g. 999999999999. This is the same value as used in the sub and uid claims.
name The End-User's full name using the format surname first name title e.g. Smith Jane Ms. Note entries created in SDS prior to 2015 may use other formats.
family_name The End-User's surname.
given_name The End-User's first name.
title The End-User's title e.g. Mr
idassurancelevel The level of assurance performed on the End-User's identity. This is a string value which can take one of the following values: 0, 1, 2 or 3. These values correspond to Identity Assurance Levels as defined in the NIST Digital Identity Guidelines for Enrollment and Identity Proofing Requirements. An assurance level of IAL3 gives a very high level of assurance of the End-User's identity including checks such as physical presence for identity proofing and verification of identifying attributes by a trained and authorized individual. Relying Parties SHOULD validate that this claim has a value appropriate for their use case. For access to national clinical systems the idassurancelevel MUST be 3. This value is already present in the ID Token as the id_assurance_level claim. See Token Request
initials The End-User's initials - comes from the initialsfield of the directory.
middle_names The End-User's middle name(s) - comes from the nhsMiddleNames field of the directory.
display_name The End-User's display name - comes from the displayName field of the directory. This is often used by an RA to specify the preferred display name of the End-User.

 

associatedorgs

The associatedorgs scope returns a JSON array of the organisations at which the End-User has a role.

Claim Description
nhsid_user_orgs A JSON array of the organisations at which the End-User has an assigned RBAC role, it contains an org_code and org_name for each organisation.
org_code The organisation's code as defined by the Organisation Data Service.
org_name The organisation's code as defined by the Organisation Data Service.

 

An example UserInfo Response is given below to illustrate the structure of the nhsid_user_orgs JSON array.

Example nhsid_user_orgs JSON array

{
   "nhsid_user_orgs":[
      {
         "org_code":"5JY",
         "org_name":"ROCHDALE PCT"
      },
      {
         "org_code":"Q14",
         "org_name":"GREATER MANCHESTER STRATEGIC HA"
      }
   ],
   "sub":"150254705103"
}

nationalrbacaccess

The nationalrbacaccess scope returns a JSON document containing the full set of National RBAC roles assigned to the End-User. Readers may find additional useful information in the section 5.5 of the SDS External Interface Specification (Word document).

Claim Description
nhsid_useruid A 12 digit identifier uniquely identifying the End-User within NHS Identity e.g. 999999999999. This is the same value as used in the sub and uid claims and corresponds to the uid of the nhsPerson in the SDS directory.
name The End-User's full name using the format surname first name title e.g. Smith Jane Ms. Note entries created in SDS prior to 2015 may use other formats.
nhsid_nrbac_roles A JSON array of each of the End-User's roles. Each entry will contain as a minimum: org_code, person_orgid, person_roleid, role_code and role_name. It may also contain arrays of activities, activity_codes, aow, aow_codes, workgroups and workgroup codes that have been assigned to the End-User's role.
org_code The organisation's code as defined by the Organisation Data Service.
person_orgid A 12 digit identifier that uniquely identifies the End-User's association with the organisation. This corresponds to the uniqueidentifier of the nhsOrgPerson object in the SDS directory.
person_roleid A 12 digit identifier that uniquely identifies the End-User's role at the organisation. This corresponds to the uniqueidentifier of the nhsOrgPersonRole object in the SDS directory. This is commonly referred to as the Role Profile Code and is used by national systems to audit what role a user was performing when they execute an action.
role_code A colon separated string of codes comprising a Primary, Secondary and Tertiary Job Role Code e.g S0080:G0440:R6050. Job role codes are typically referred to by their tertiary code which is a unique value e.g. R6050.
role_name A colon separated string of names comprising a Primary, Secondary and Tertiary Job Role Name e.g. "Admin & Clerical":"Admin":"Clinical Coder".  Job role names are typically referred to by their tertiary name e.g. Clinical Coder. Note that the name parts are enclosed in "s as they may include special characters.
activity_codes An array of Activity Codes assigned to the End-User's job role e.g. B0021. Only Activity Codes explicitly granted to the job role are listed, the full set of activities that the End-User can perform must be determined by reference to the National RBAC Database (Excel spreadsheet) [Archive Content].
activities An array of Activity Names assigned to the End-User's job role e.g. Perform Discharge Administration. The order of entries in this array is not guaranteed to be the same as that for the associated codes.
aow_codes An array of Area of Work Codes assigned to the End-User's job role. Each code comprises a colon separated string of a Primary, Secondary and Tertiary Area of Work Code e.g P0010:Q0190:T0450. Area of Work Codes are typically referred to by their tertiary code which is a unique value e.g. T0450. Area of work codes in conjunction with role code can be used to determine the full set of activities that the End-User can perform by reference to the National RBAC Database (Excel spreadsheet) [Archive Content].
aow

An array of Area of Work Names assigned to the End-User's job role. Each name comprises a colon separated string of a Primary, Secondary and Tertiary Area of Work Name e.g "Medicine":"Gastroenterology":"Hepatology". Area of Work Names are typically referred to by their tertiary name e.g. Hepatology. Note that the name parts are enclosed in "s as they may include special characters. The order of entries in this array is not guaranteed to be the same as that for the associated codes.
workgroups_codes An array of codes identifying the Work Groups of which the End-User's job role is a member e.g. 150255301108.
workgroups An array of names of the Work Groups of which the End-User's job role is a member e.g. Clinical Workgroup

 

An example UserInfo Response is given below to illustrate the structure of the nhsid_nrbac_roles JSON array for a job role that has all attributes populated with more than one value.

Example nhsid_nrbac_roles JSON array for a job role with all attributes

{
   "nhsid_useruid":"150254705103",
   "name":"Grace Richard Mr",
   "nhsid_nrbac_roles":[
      {
         "activities":[
            "Perform Discharge Administration",
            "Print Discharge Summary",
            "View Discharge Summary"
         ],
         "activity_codes":[
            "B0021",
            "B0022",
            "B0019"
         ],
         "aow":[
            "\"Medicine\":\"Gastroenterology\":\"Hepatology\"",
            "\"Medicine\":\"General Medicine\":\"Acute Medicine\""
         ],
         "aow_codes":[
            "P0010:Q0190:T0450",
            "P0010:Q0010:T0010"
         ],
         "org_code":"5JY",
         "person_orgid":"150255293108",
         "person_roleid":"150255303100",
         "role_code":"S0010:G0020:R0050",
         "role_name":"\"M&D\":\"Medical - M&D\":\"Consultant\"",
         "workgroups":[
            "Clinical Workgroup",
            "Clinical Sub-Workgroup"
         ],
         "workgroups_codes":[
            "150255301108",
            "150255302109"
         ]
      }
   ],
   "sub":"150254705103"
}

The following example shows a user with two roles in different organisations. Note that if an attribute is not populated in the SDS directory then no value is provided.

Example of user with two roles in different organisations

{
   "nhsid_useruid":"150254705103",
   "name":"Grace Richard Mr",
   "nhsid_nrbac_roles":[
      {
         "org_code":"Q14",
         "person_orgid":"150255297102",
         "person_roleid":"150255298103",
         "role_code":"S0080:G0440:R6050",
         "role_name":"\"Admin & Clerical\":\"Admin\":\"Clinical Coder\""
      },
      {
         "org_code":"5JY",
         "person_orgid":"150255293108",
         "person_roleid":"150255294109",
         "role_code":"S0010:G0020:R0100",
         "role_name":"\"M&D\":\"Medical - M&D\":\"Clinical Assistant\""
      }
   ],
   "sub":"150254705103"
}

professionalmemberships

This scope returns details of the End-User's membership of professional bodies.

Claim Description
gmc_id

The End-User’s GMC Number. A 7 digit numeric code e.g 0010856.
gdp_id The End-User’s General Dental Practitioner Number (GDP).  A letter 'D' followed by 7 digit numeric code e.g. D2015293.
gdc_id The End-User’s General Dental Council (GDC) number. A 5 digit numeric code e.g. 79005.
rcn_id The End-User’s Royal College of Nursing Number (RCN).  A 7 digit numeric code e.g. 1234567.
gmp_id The End-User’s Doctor’s Index Number formerly known as the General Medical Practitioner Code (GMP). A 6 digit numeric code e.g. 041649.
nmc_id The End-User’s Nursing and Midwifery Council Number (NMC).  An 8 character code e.g. 12A1234A.
consultant_id The End-User’s Consultant Code. A letter 'C' followed by the GMC code e.g. C0010856.
gphc_id The End User’s General Pharmacy Council (GPhC) number.  An 8 digit code consisting of an alpha and seven alpha/numeric fields e.g. A123456A.
ocspr_code The End User's OCS Practitioner Code - from the nhsOCSPRCode directory field. An 8 character code consisting of a G followed by 7 digits - e.g. G3468184

 

Note Relying Parties SHOULD NOT rely on the values of the claims as these are not actively managed by Care Identity Service.

organisationalmemberships

This scope returns details of the End-User's membership of professional bodies in the context of the organisations for which they work.

Claim Description
nhsid_org_memberships A JSON array of the organisations for which the End-User has professional memberships, it contains an org_code, org_name and gnc value for each organisation.
org_code The code of the organisation at which the End-User has the role as defined by the Organisation Data Service.
org_name The code of the organisation at which the End-User has the role as defined by the Organisation Data Service.
person_orgid A 12 digit identifier that uniquely identifies the End-User's association with the organisation. This corresponds to the uniqueidentifier of the nhsOrgPerson object in the SDS directory.
gnc The End-User’s General National Code provided by the NHS Prescription service to track prescribing activity. A code represents a prescribing cost codes and is only unique in conjunction with a organisation association. A letter 'G' followed by a 6 digit numeric code e.g.  G0010856.

 

An example UserInfo Response is given below to illustrate the structure of the nhsid_user_orgs JSON array.

Example nhsid_user_orgs JSON array

{
   "nhsid_org_memberships":[
      {
         "org_code":"5JY",
         "org_name":"ROCHDALE PCT",
         "person_orgid":"150255293108",
         "gnc":"G0010856"
      }
   ],
   "sub":"150254705103"
}

Last edited: 7 May 2025 1:37 pm