Claims

The claim is a piece of information about the user. The client application can request the claims about the end-user authentication. OpenID Connect defines a standard set of basic profile Claims. Pre-defined sets of claims can be requested using specific scope values. The Client application can also request additional claims. These additional claims must be defined on the OpenID Connect configuration on the admin portal.

In CyberArk Identity, the claims can be requested either using the ID token or the userinfo endpoint.

Standard Claims

The following standard claims can be requested as part of the userinfo response or ID token by default using CyberArk Identity:

Member	Type	Description
name	String	End-User's full name
given_name	String	Given the End-User's name(s) or first name(s). The value is same as the end user's full name.
family_name	String	Surname(s) or last name(s) of the End-User. The value is same as the end user's full name.
preferred_username	String	Shorthand name by which the End-User wishes to be referred to at the RP, such as janedoe or j.doe.
unique_name	String	The unique name for the user.
email	String	End-User's preferred email address.
email_verified	String	True if the End-User's email address has been verified; otherwise, false.
phone_number	String	End-User's preferred telephone number.
phone_number_verified	String	True if the End-User's phone number has been verified; otherwise, false.

Additional claims can be requested in conjunction with the standard claims.

Requesting claims using scopes

In OpenID Connect, the scope values can also be used to retrieve claims. Authorization Servers treat claims requested by the following scopes as voluntary claims.

CyberArk Identity supports the following scope values that are used to request standard claims:

Scope name	Description
profile	This scope value requests access to the end user's default profile claims, which are name, family_name, given_name, middle_name, nickname, preferred_name, profile, picture, website, gender, birthdate, zoneinfo, locale, and updated_at
email	This scope value requests access to the email and email_verified claims.
address	This scope value requests access to the address claim.
phone	This scope value requests access to the phone_number and phone_number_verified claims.

Note: These scopes need not be added to the list of authorized scopes as they are predefined.

Requesting other standard claims

To request other standard claims, not by default sent by CyberArk Identity, such as gender, nickname, address (or), to modify the value of the default claims sent by CyberArk Identity such as preferred_name or family_name, the admin has to add/modify them explicitly using the script editor.

The attributes such as preferred_name, nickname, and address are not standard attributes in CyberArk Identity. Hence they have to be added as additional attributes.

For example, consider the below user for whom the following additional attributes are added:

Admin should add the below script in the script editor:

The client requests for profile and address scopes through the below authorization request:

POST {{tenant_url}}/oauth2/authorize/{{application_id}}?debug={{debug}}&scope=openid profile address&response_type={{response_type}}&redirect_uri={{redirect_uri}}&client_id={{client_id}}&client_secret={{client_secret}}&nonce=abc

The ID token received by the client will contain the below information:

{
  "auth_time": 1661741241,
  "iss": "<tenant_url>/<application_id>/",
  "given_name": "monika.a",
  "iat": 1661746081,
  "aud": "<client_id>",
  "name": "monika.a",
  "family_name": "monika.a",
  "address": "500081",
  "preferred_username": "abc",
  "unique_name": "monika.a",
  "exp": 1661764081,
  "sub": "<user_uuid>",
  "nonce": "abc",
  "nickname": "moni"
}

Custom scopes and claims

Apart from the predefined claims, custom claims can also be requested for the authenticated user using the script editor.

For example, consider an attribute called "department" that gives information about the department where the user works.

Admin should add the below script in the script editor:

The ID token will contain the claim department as below:

{
  "auth_time": 1661741241,
  "iss": "<tenant_url>/<application_id>/",
  "given_name": "monika.a",
  "iat": 1661747156,
  "aud": "<client_id>",
  "name": "monika.a",
  "family_name": "monika.a",
  "preferred_username": "monika.a",
  "unique_name": "monika.a",
  "exp": 1661765156,
  "sub": "<user_uuid>",
  "nonce": "abc",
  "department": "HR"
}

You can also control how the claims should be retrieved using custom scopes as below:

The client requests for department scopes through the below authorization request:

POST {{tenant_url}}/oauth2/authorize/{{application_id}}?debug={{debug}}&scope=openid department&response_type={{response_type}}&redirect_uri={{redirect_uri}}&client_id={{client_id}}&client_secret={{client_secret}}&nonce=abc

❗️
Early access feature
It is mandatory to add the custom scopes to the authorized scope list such that the authorization server can validate the scopes sent by the client and only authorized scopes are processed.