The application attributes service lets you customize the content of an ID token or a SAML assertion by adding custom attributes and their values. Custom attributes have a cumulative length constraint of 16 Kb. See Custom attributes in Schemas for more information.
For OpenID Connect (OIDC) applications, the user claim defined by the custom attribute mapping is returned in the ID token, regardless of the scopes specified in the authorization request. For example, suppose you want to include a user’s accountId
in ID tokens associated with the specified OIDC application, a custom application attribute resource can be created to map the user’s account ID to the accountId
PingOne user attribute. The request looks like this:
curl -X "POST" "https://api.pingone.com/v1/environments/{{envID}}/applications/{{appID}}/attributes" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d '{
"name": "userAccountID",
"value": "${user.accountId}",
"required": true
}'
For SAML applications, the user claim defined by the custom attribute mapping is returned in the SAML assertion.
For example, suppose you want to include an externalId
in assertions associated with the specified SAML application, a custom application attribute resource can be created to map the SAML externalId
attribute to the user’s external ID attribute. The request looks like this:
curl -X "POST" "https://api.pingone.com/v1/environments/{{envID}}/applications/{{appID}}/attributes" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d '{
"name": "externalId",
"value": "${user.externalId}",
"required": true
}'
You can use PingOne’s expression language for advanced attribute mapping. The supported expression language is an augmentation of SpEL. SpEL is a powerful expression language used for querying and manipulating an object graph at runtime.
For example, with advanced attribute mapping capabilities, you can write an expression that concatenates two or more user attributes in the value
property:
curl -X "POST" "https://api.pingone.com/v1/environments/{{envID}}/applications/{{appID}}/attributes" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d '{
"name": "fullName",
"value": "${user.name.given + ', ' + user.name.family}",
"required": true
}'
In this request, the fullName
mapped attribute includes the user’s first name and last name in the response.
Property | Type | Required? | Mutable? | Description |
---|---|---|---|---|
application.id |
String | Required | Read only | A string that specifies the application associated with the application mapping resource. |
createdAt |
Date | Read only | The time the resource was created. | |
environment.id |
String | Required | Read only | A string that specifies the environment associated with the application mapping resource. |
id |
UUID | Required | Read only | A string that specifies the application mapping ID. |
mappingType |
String | Optional | Mutable | A string that specifies the mapping type of the attribute. Options are CORE , SCOPE , and CUSTOM . The CORE and SCOPE mapping types are for reserved attributes managed by the API and cannot be removed. Attribute values for these mapping types can be updated. The CUSTOM mapping type is for user-defined attributes. Attributes of this type can be updated and deleted. |
name |
String | Required | Immutable | A string that specifies the name of attribute and must be unique within an application. The property is set on create only and cannot be changed after creation. For SAML applications, the samlAssertion.subject name is a reserved case-insensitive name which indicates the mapping to be used for the subject in an assertion. For OpenID Connect applications, the following names are reserved and cannot be used:
|
required |
Boolean | Required | Mutable | A boolean to specify whether a mapping value is required for this attribute. If true, a value must be set and a non-empty value must be available in the SAML assertion or ID token. |
updatedAt |
Date | Read only | The time the resource was updated. | |
value |
String | Required | Mutable | A string that specifies the string constants or expression for mapping the attribute path against a specific source. The expression format is: ${<source>.<attribute_path>} . The only supported source is user (for example, ${user.id} ). This is a required property. |
Property | Type | Required? | Mutable? | Description |
---|---|---|---|---|
sub |
String | Required | Mutable | A string that specifies the core OIDC application mapping attribute. The default user attribute value is ${user.id} and the required property value must be set to true . |
Property | Type | Required? | Mutable? | Description |
---|---|---|---|---|
saml_subject |
String | Required | Mutable | A string that specifies the core SAML mapping attribute. The default user attribute value is ${user.id} and the required property value must be set to true . |
Code | Message |
---|---|
200 | Successful operation. |
201 | Successfully created. |
204 | Successfully removed. No content. |
400 | The request could not be completed. |
401 | You do not have access to this resource. |
403 | You do not have permissions or are not licensed to make this request. |
404 | The requested resource was not found. |
500 | An unexpected error occurred. |