Define and request claims

This topic explains how to use claims in CyberArk Identity APIs.

A claim is a piece of information about a user. The client application can request claims about an end-user's authentication. OpenID Connect defines a standard set of basic profile claims, and 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, you can request the claims either using the ID token or the UserInfo endpoint.

Request standard claims

You can request the following standard claims as part of the UserInfo response or ID token by default, using CyberArk Identity:

Member	Type	Description
name	String	The end-user's full name
given_name	String	The end-user's given name(s) or first name(s) The value is same as the end user's full name.
family_name	String	The end user's surname(s) or last name(s) The value is same as the end user's full name.
preferred_username	String	A shorthand name by which the end-user wants to be referred at the RP, such as janedoe or j.doe
unique_name	String	A unique name for the user
email	String	The 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	The end-user's preferred telephone number
phone_number_verified	String	True if the end-user's phone number has been verified; otherwise, false

Request claims using scopes

In OpenID Connect, 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	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.

Request other standard claims

You can request other standard claims, which are not sent by CyberArk Identity by default, 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. To do this, you can add or modify them explicitly using the script editor.

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

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

Add the script below, in the script editor:

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

The ID token received by the client contains the following information:

Request custom scopes and claims

Apart from the predefined claims, you can also request custom claims 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.

Add the script below, in the script editor:

The ID token contains the claim called department, as shown below:

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

The client requests the department scopes through the following authorization request: