ID token and SAML assertion customization

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.

In the Authorization request header field of all samples, the accessToken value is your full base64url-encoded JSON web token generated by the authentication service.

OpenID Connect application attribute mappings

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 accessToken' \
-d '{
	"name": "userAccountID",
	"value": "${user.accountId}",
	"required": true
}'

SAML application attribute mappings

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 accessToken' \
-d '{
	"name": "externalId",
	"value": "${user.externalId}",
	"required": true
}'

Advanced attribute mapping

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 accessToken' \
-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.

Applications attribute mapping data model {#applications-attribute-mapping-data-model}

Property Type Required? Mutable? Description
application.id String Required Read-only The application associated with the application mapping resource.
createdAt Date N/A Read-only The time the resource was created.
environment.id String Required Read-only The environment associated with the application mapping resource.
id UUID Required Read-only The application mapping ID.
mappingType String Optional Mutable 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 The name of attribute. 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:
  • acr
  • amr
  • at_hash
  • aud
  • auth_time
  • azp
  • client_id
  • exp
  • iat
  • iss
  • jti
  • nbf
  • nonce
  • org
  • scope
  • sid
  • sub
nameFormat String Optional Mutable A URI reference representing the classification of the attribute. Helps the service provider interpret the attribute format.
required Boolean Required Mutable 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 N/A Read-only The time the resource was updated.
value String Required Mutable 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}).
idToken Boolean Optional Mutable Whether the attribute mapping should be available in the ID Token. This property is applicable only when the application’s protocol property is OPENID_CONNECT. If omitted, the default is true. Note that the idToken and userInfo properties cannot both be set to false. At least one of these properties must have a value of true.
userInfo Boolean Optional Mutable Whether the attribute mapping should be available through the /as/userinfo endpoint. This property is applicable only when the application’s protocol property is OPENID_CONNECT. If omitted, the default is true. Note that the idToken and userInfo properties cannot both be set to false. At least one of these properties must have a value of true.
oidcScopes List Optional Mutable OIDC resource scope IDs that this attribute mapping is available for exclusively. This setting overrides any global OIDC resource scopes that contain an attribute mapping with the same name. The list can contain only scope IDs that have been granted for the application through the /grants endpoint. A null value is accepted for backwards compatibility. However, an empty set is invalid, and one scope ID is expected. If null, the response includes this mapping in the openid scope.

OIDC application core mapping attributes

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.

SAML application core mapping attributes

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.

Audit reporting events

To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

Service Event
applications ATTRIBUTE.CREATED
applications ATTRIBUTE.UPDATED
applications ATTRIBUTE.DELETED

Response codes

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.