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. A custom attribute is name-value pair that references either a PingOne user schema attribute or a static value. Custom attributes convey additional information about the user to applications.

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/{environmentId}/applications/{applicationId}/attributes" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-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/{environmentId}/applications/{applicationId}/attributes" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d '{
	"name": "externalId",
	"value": "${user.externalId}",
	"required": true
}'

Applications attribute mapping API operations

The applications attribute mapping endpoints support the following operations:

For hands-on experience with the applications API endpoints, click the Run in Postman button below to download a Postman collection that you can import and open in your local Postman application.

Applications attribute mapping data model

Property Description
createdAt The time the resource was created.
mappingType 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 A string that specifies the name of attribute and must be unique within an application. 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
This is a required property.
required 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 The time the resource was updated.
value 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.

OIDC application core mapping attributes

Property Description
sub 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 Description
saml_subject 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.

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.

Note: You need the Client Application Developer role to perform operations on application resources.

Endpoint examples

Get application attributes

The GET /environments/{environmentId}/applications/{applicationId}/attributes endpoint returns a list of all application attribute mappings for the application specified by its ID in the request URL.

curl -X "GET" "https://api.pingone.com/v1/environments/{environmentId}/applications/{applicationId}/attributes" \
-H 'Authorization: Bearer jwtToken'

The response data looks like this:

{
  "_links": {
    "self": {
      "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/applications/fe36bb1a-3983-4d6c-af02-e7d50b0ab99a/attributes"
    }
  },
  "_embedded": {
    "attributes": [
      {
        "_links": {
          "self": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/applications/fe36bb1a-3983-4d6c-af02-e7d50b0ab99a/attributes/f6d41400-e571-432e-9151-4ff06e0b51ce"
          }
        },
        "id": "f6d41400-e571-432e-9151-4ff06e0b51ce",
        "mappingType": "CORE",
        "environment": {
          "id": "9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
        },
        "application": {
          "id": "fe36bb1a-3983-4d6c-af02-e7d50b0ab99a"
        },
        "createdAt": "2019-10-29T16:33:41.479Z",
        "updatedAt": "2019-10-29T16:33:41.479Z",
        "name": "sub",
        "value": "${user.id}",
        "required": true
      },
      {
        "_links": {
          "self": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/applications/fe36bb1a-3983-4d6c-af02-e7d50b0ab99a/attributes/18d4b06c-f8f3-4064-a2c4-0db80250fb5f"
          }
        },
        "id": "18d4b06c-f8f3-4064-a2c4-0db80250fb5f",
        "mappingType": "CUSTOM",
        "environment": {
          "id": "9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
        },
        "application": {
          "id": "fe36bb1a-3983-4d6c-af02-e7d50b0ab99a"
        },
        "createdAt": "2019-10-29T16:35:07.847Z",
        "updatedAt": "2019-10-29T16:35:07.847Z",
        "name": "email",
        "value": "${user.email}",
        "required": false
      }
    ]
  },
  "size": 2
}

Get one application attribute

To get data for a single attribute mapping associated with an application resource, the GET /environments/{environmentId}/applications/{applicationId}/attributes/{attributeId} operation returns data only for the application resource with the specified ID.

curl -X GET "https://api.pingone.com/v1/environments/{environmentId}/applications/{applicationId}/attributes/{attributeId}" \
-H "Authorization: Bearer jwtToken"

The response data looks like this:

{
  "_links": {
    "self": {
      "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/applications/fe36bb1a-3983-4d6c-af02-e7d50b0ab99a/attributes/18d4b06c-f8f3-4064-a2c4-0db80250fb5f"
    },
    "application": {
      "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/applications/fe36bb1a-3983-4d6c-af02-e7d50b0ab99a"
    }
  },
  "id": "18d4b06c-f8f3-4064-a2c4-0db80250fb5f",
  "mappingType": "CUSTOM",
  "environment": {
    "id": "9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
  },
  "application": {
    "id": "fe36bb1a-3983-4d6c-af02-e7d50b0ab99a"
  },
  "createdAt": "2019-10-29T16:35:07.847Z",
  "updatedAt": "2019-10-29T16:35:07.847Z",
  "name": "email",
  "value": "${user.email}",
  "required": false
}

Add application attributes

The POST /environments/{environmentId}/applications/{applicationId}/attributes operation adds a new attribute mapping to the application resource specified by its ID in the request URL.

curl -X "POST" "https://api.pingone.com/v1/environments/{environmentId}/applications/{applicationId}/attributes" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d '{
	"name": "email",
	"value": "${user.email}",
	"required": false
}'

In the request body, the name and value attributes are required. All other attribute values are optional for the POST request.

The response data looks like this:

{
  "_links": {
    "self": {
      "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/applications/fe36bb1a-3983-4d6c-af02-e7d50b0ab99a/attributes/18d4b06c-f8f3-4064-a2c4-0db80250fb5f"
    },
    "application": {
      "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/applications/fe36bb1a-3983-4d6c-af02-e7d50b0ab99a"
    }
  },
  "id": "18d4b06c-f8f3-4064-a2c4-0db80250fb5f",
  "mappingType": "CUSTOM",
  "environment": {
    "id": "9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
  },
  "application": {
    "id": "fe36bb1a-3983-4d6c-af02-e7d50b0ab99a"
  },
  "createdAt": "2019-10-29T16:35:07.847Z",
  "updatedAt": "2019-10-29T16:35:07.847Z",
  "name": "email",
  "value": "${user.email}",
  "required": false
}

Update application attributes

The PUT /environments/{environmentId}/applications/{applicationId}/attributes/{attributeId} operation updates the attribute mapping specified by its ID in the request URL.

curl -X "PUT" "https://api.pingone.com/v1/environments/{environmentId}/applications/{applicationId}/attributes/{attributeId}" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d '{
	"name": "email",
	"value": "${user.email}",
	"required": true
}'

The response data looks like this:

{
  "_links": {
    "self": {
      "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/applications/fe36bb1a-3983-4d6c-af02-e7d50b0ab99a/attributes/18d4b06c-f8f3-4064-a2c4-0db80250fb5f"
    },
    "application": {
      "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/applications/fe36bb1a-3983-4d6c-af02-e7d50b0ab99a"
    }
  },
  "id": "18d4b06c-f8f3-4064-a2c4-0db80250fb5f",
  "mappingType": "CUSTOM",
  "environment": {
    "id": "9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
  },
  "application": {
    "id": "fe36bb1a-3983-4d6c-af02-e7d50b0ab99a"
  },
  "createdAt": "2019-10-29T16:35:07.847Z",
  "updatedAt": "2019-10-29T16:35:07.847Z",
  "name": "email",
  "value": "${user.email}",
  "required": true
}

Delete application attributes

To delete an application attribute mapping associated with an application resource, you need to specify the the application resource ID and the attribute ID. The DELETE /environments/{environmentId}/applications/{applicationId}/attributes/{attributeId} operation deletes the identified SAML attribute mapping from the specified application.

curl -X "DELETE" "https://api.pingone.com/v1/environments/{environmentId}/applications/{applicationId}/attributes/{attributeId}" \
-H 'Authorization: Bearer jwtToken'

For successful delete operations, a 204 NO CONTENT message is returned by the request.