PingOne Platform APIs

Application Attribute Mapping

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. Refer to Custom attributes in Schemas for more information.

If you have multiple identity providers (IdPs) configured, you need to include an attribute mapping for IDP ID to distinguish between the IdPs.

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.

For more information about PingOne’s expression language, refer to PingOne’s expression language.

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

Required

Read-only

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.

The core attribute mapping is created automatically when the OpenID Connect or SAML application is created.

Application Attribute events generated

Refer to Audit Reporting Events for the events generated.

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.

Application attribute mapping errors

In addition to the general error codes, application attribute mapping operations can return the following errors:

HTTP status Top‑level code Detail code When it happens and what the response contains

400

INVALID_REQUEST

INVALID_VALUE

Message: The request could not be completed. The request was malformed or invalid.

When and details

When: The application’s protocol does not support application attributes

Details:

Attributes are only supported for applications with protocols [SAML, OPENID_CONNECT] and not applicable to the '<protocol>' application [<appID> - <appName>] in environment '<envID>

400

INVALID_DATA

UNIQUENESS_VIOLATION

Message: Identifies the conflicting mapping name.

When and details

When: A custom mapping name duplicates an existing mapping or a reserved core mapping name

Details: name already exists

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request violates a constraint imposed by the service.

When and details

When: Creating or updating a mapping would exceed the application’s maximum number of mappings (100)

Details: Application has reached maximum amount of attributes: Application '<appID>' in Environment '<envID>'

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: The mapping name is reserved or is invalid for the application’s protocol

Details: Describes the invalid name.

400

INVALID_DATA

INVALID_VALUE

Message: For an invalid expression, describes the rejected reference, such as Unsupported property / object reference - [<expression>] are not allowed for this expression.; for an invalid name format, Validation Error : [nameFormat is not valid]

When and details

When: A mapping expression or name format is invalid

Details: For an expression, expression not valid; for a name format, is not valid

400

INVALID_DATA

EMPTY_VALUE

Message: Validation Error : [value must not be blank]

When and details

When: A mapping value is empty or null where the protocol does not allow it — SAML and WS‑Federation mappings reject blank values regardless of required, and OIDC core mappings reject empty or null values

Details: must not be blank. OIDC custom mappings allow empty values when required is false; with required: true a blank value uses the separate constraint‑violation response.

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request could not be completed. There was an issue processing the request.

When and details

When: An OIDC mapping configuration is inconsistent: both idToken and userInfo are false, oidcScopes is empty or ungranted, or a required custom mapping has an empty value

Details: Attribute userInfo must be true if idToken is false., oidcScopes must be null or contain at least one item, oidcScopes contains an invalid scope which has not been granted for the application, or value cannot be blank when required is set

400

INVALID_DATA

INVALID_VALUE

Message: Identifies the core mapping and the rejected property or value.

When and details

When: An update changes the immutable name or required property of a core mapping, or supplies a literal value for a core mapping

Details: property cannot be changed or Core attribute cannot have literal/static values

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: Identifies the unsupported operation and mapping.

When and details

When: DELETE /attributes/{attributeID} targets a core mapping

Details: operation not supported

403

ACCESS_FAILED

None

Message: The actor attempting to perform the request is not authorized.

When and details

When: The actor lacks the applications:read:application permission (the GET operations), the applications:update:application permission (the POST and PUT operations), or the applications:delete:application permission (the DELETE operation)

Details: None.

404

NOT_FOUND

None

Message: Identifies the application and environment.

When and details

When: The application does not exist, or is a self‑service, admin console, or application portal application (applies to all application attribute mapping operations)

Details: None.

404

NOT_FOUND

None

Message: Identifies the attribute mapping, application, and environment.

When and details

When: GET, PUT, or DELETE /attributes/{attributeID} references an attribute mapping that does not exist

Details: None.