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. |
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 |
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.
Updated about 1 year ago