--- title: Application Attribute Mapping description: 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. component: pingone-api page_id: pingone-api:platform:applications/application-attribute-mapping canonical_url: https://developer.pingidentity.com/pingone-api/platform/applications/application-attribute-mapping.html section_ids: id-token-and-saml-assertion-customization: ID token and SAML assertion customization openid-connect-application-attribute-mappings: OpenID Connect application attribute mappings saml-application-attribute-mappings: SAML application attribute mappings advanced-attribute-mapping: Advanced attribute mapping applications-attribute-mapping-data-model: Applications attribute mapping data model oidc-application-core-mapping-attributes: OIDC application core mapping attributes saml-application-core-mapping-attributes: SAML application core mapping attributes application-attribute-events-generated: Application Attribute events generated response-codes: Response codes --- # 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](../schemas.html) 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: ```sh 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: ```sh 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: ```sh 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](https://docs.pingidentity.com/pingone/pingone_expression_language/p1_expression_language.html). | ## 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: `${.}`. 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](../reference/audit-reporting-events.html) 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. |