4. Scopes and claims

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 Care Identity 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 Care Identity Authentication OpenID Provider.

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

Extended Scopes supported by the Care Identity 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.
universalaccess	Reserved for later use. This SHOULD NOT be used.
orgaccess	Reserved for later use. This SHOULD NOT be used.
odscodes	Reserved for later use. This SHOULD NOT be used.

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, Care Identity 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 the Care Identity Authentication, such as 999999999999. This is the same value as used in the sub claim.

email

This is the standard OpenID Connect profile scope, Care Identity 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 the Care Identity 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 that currently only the GMC Number, Doctor's Index Number (GMP) and Consultant Code are actively managed. Relying Parties SHOULD NOT rely on the values of the remaining claims.

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"
}

All chapters

Last edited: 30 January 2024 9:19 am