PingOne

Expressions and concatenation

Property reference expressions

Property reference expressions are the most common expression pattern to refer to a JSON object property using dotted syntax, object.property1, or map access syntax, object[property].

Any property that begins with a letter and only contains letters, numbers or underscores can be accessed using dot notation or map access syntax, for example:

  • user.accountId

  • user.name.given

  • user['accountId']

  • user['name']['given']

If a property contains a character other than the ones mentioned previously, such as a hyphen or dollar sign, it can only be accessed using the map access syntax, for example user.name['full-name'] or providerAttributes['amountIn$'].

Literal expressions

PingOne supports literal expressions in the form of strings, numeric values, boolean, and null.

Strings are delimited by single quotation marks. To put a single quotation mark itself in a string, use two single quotation mark characters around it. For example, '''string''' returns 'string'.

Numeric literals used directly in expressions must adhere to Java standards, such as adhering to min and max limits and using l or L for long literals. Numeric literals are also subject to the Java floating point rounding issues.

Expression type Example

String in double quotes

"Hello"

String in single quotes

'Hello', '''Hello'''

Numbers

1, 8.57, 34533535454345L

Boolean

true or false

String concatenation

You can use the + operator to concatenate values. You must include a leading and trailing space around the operator.

For example, user.name.family + ', ' + user.name.given or 'Hi'
user.name.given.

Because it’s missing a leading space, 'Hi'+ user.name.given will return an error.

Using expressions to retrieve Microsoft Entra attributes

You can use expressions in PingOne to retrieve custom user attributes from Microsoft Entra ID. Learn more in Add custom data to resources using extensions in the Microsoft Entra documentation.

PingOne supports three types of Microsoft Entra attributes:

Extension attributes

Extension attributes in Microsoft Entra are custom attributes you can use to add information about a user or device, such as an employee ID or organizational unit (OU), when syncing on-premise Active Directory (AD) to Microsoft Entra. Microsoft Entra supports 15 extension attribute properties and assigns 1 - 15 to the end of the attribute property name in the order you create them, such as extensionAttribute1 for the first custom attribute and so on.

Before you begin

Steps

  1. Review the extension attribute number assigned in Microsoft Entra for any attributes you want to map to PingOne:

    1. In the Microsoft Entra admin center, go to Users and select a user with an extension attribute.

    2. In the On-premises section, click View next to Extension attributes.

      Result:

      Any extension attributes configured for this user display as numbered attributes, such as Extension attribute 11 with an example value of Account Executive.

    3. Confirm the assigned number for any extension attributes you want to map to a PingOne user attribute, such as Extension attribute 11 in this example.

      You’ll need the number when adding an expression in PingOne.

  2. Map an extension attribute to a PingOne user attribute:

    1. In the PingOne admin console, go to Integrations > External IdPs and browse or search for the Microsoft IdP.

    2. Click the Microsoft IdP to open the details panel.

    3. On the Attributes tab, click the Pencil icon.

    4. Click the Gear icon next to an attribute mapping to open the Build and Test Expression modal. Learn more in Using the expression builder and Mapping attributes.

      To add a new attribute, click Add.

    5. In the modal, enter an expression in the Expression field in the following format:

      providerAttributes.onPremisesExtensionAttributes.extensionAttribute<number>

      where <number> can be 1 - 15 based on the extension attribute number you want to map from Microsoft Entra.

      Example:

      For Extension attribute 11, use the following format:

      providerAttributes.onPremisesExtensionAttributes.extensionAttribute11

    6. Click Save.

    7. On the Attributes tab, click Save.

    Result

    PingOne populates the extension attribute value from Microsoft Entra as the value for this user attribute. For example, Account Executive for Extension attribute 11.

The user attribute in PingOne must have Type set to STRING, and Multi-valued can be set to Yes or No. Learn more in Viewing user attributes.

Directory extensions

Directory extensions can be used to add a custom property to directory objects without requiring an external data store and don’t come from on-premise AD. For example, you can add a custom property for user job groups, such as jobGroupTracker.

You must first register a directory extension on an application through the Create extensionProperty operation in Microsoft Entra and then target the directory extension to specific directory objects. Learn more in Directory extensions in the Microsoft Entra documentation.

Before you begin

Add Microsoft as an identity provider (IdP) in PingOne.

Steps

  1. In the Microsoft Entra admin center, define a directory extension on an application.

    Learn more in the Microsoft Entra documentation.

    Use the same application ID in Microsoft Entra used when creating the Microsoft IdP connection in PingOne. Learn more in Adding Microsoft as an identity provider (IdP) in PingOne.

    Example:

    You can define a directory extension named jobGroupTracker to identify user job groups. In the response, the directory extension property name is returned as follows:

    "name": "extension_b7d8e648520f41d3b9c0fdeb91768a0a_jobGroupTracker"

    You can find a sample response in the Microsoft Entra documentation.

  2. Define the value of the directory extension to a target object, such as a specific user, in the Microsoft Entra admin center.

    Example:

    You can add a value, such as JobGroupN, for the directory extension property jobGroupTracker that can be assigned to specific users as follows:

    "extension_b7d8e648520f41d3b9c0fdeb91768a0a_jobGroupTracker": "JobGroupN"

    You can find an example in the Microsoft Entra documentation.

  3. Map the directory extension to a PingOne user attribute:

    1. In the PingOne admin console, go to Integrations > External IdPs and browse or search for the Microsoft IdP.

    2. Click the Microsoft IdP to open the details panel.

    3. On the Attributes tab, click the Pencil icon.

    4. Click the Gear icon next to an attribute mapping to open the Build and Test Expression modal. Learn more in Using the expression builder and Mapping attributes.

      To add a new attribute, click Add.

    5. In the modal, enter an expression in the Expression field in the following format:

      providerAttributes.<name>

      where <name> is the property name from the response in the Microsoft Entra admin center.

      Example:

      For a directory extension property with the name of extension_b7d8e648520f41d3b9c0fdeb91768a0a_jobGroupTracker, use the following format:

      providerAttributes.extension_b7d8e648520f41d3b9c0fdeb91768a0a_jobGroupTracker

  4. Click Save.

  5. On the Attributes tab, click Save.

    Result

    PingOne populates the directory extension property value from Microsoft Entra, such as JobGroupN, for this user attribute.

The user attribute in PingOne must have Type set to STRING, and Multi-valued can be set to Yes or No. Learn more in Viewing user attributes.

Schema extensions

Schema extensions allow you to add custom data to a resource type. For example, you can add custom properties to a user resource type to identify additional attributes for users, such as assigning training course data to particular users.

Similar to directory extensions, you must first define a schema extension in Microsoft Entra and then target the schema extension to a specific resource, such as a group.

Before you begin

Add Microsoft as an identity provider (IdP) in PingOne.

Steps

  1. In the Microsoft Entra admin center, define a schema extension.

    Learn more in Adding custom data to groups using schema extensions in the Microsoft documentation.

  2. Define the value of the schema extension to a target object, such as a specific user.

    Learn more in Add a schema extension to a resource instance in the Microsoft documentation.

  3. Map the schema extension to a PingOne user attribute:

    1. In the PingOne admin console, go to Integrations > External IdPs and browse or search for the Microsoft IdP.

    2. Click the Microsoft IdP to open the details panel.

    3. On the Attributes tab, click the Pencil icon.

    4. Click the Gear icon next to an attribute mapping to open the Build and Test Expression modal. Learn more in Using the expression builder and Mapping attributes.

      To add a new attribute, click Add.

    5. In the modal, enter an expression in the Expression field in either of the following formats.

      Choose from:

      • Single-valued attribute: To map a schema extension and one of its properties to a PingOne user attribute, use the following format:

        providerAttributes.<id>.<name>

        where <id> is the ID of the schema extension, and <name> is the name of the specific property you want to map from the Microsoft Entra admin center.

        Example:

        For a schema extension named graphLearnCourses, Microsoft Entra returns an ID for the schema extension of extkmpdyld2_graphLearnCourses in the response. For this schema extension, you can define a property with the name of courseId to assign to a user. This ID and property name are used in the expression in PingOne as follows:

        providerAttributes.extkmpdyld2_graphLearnCourses.courseId

        Learn more in Add a schema extension to a resource instance in the Microsoft Entra documentation.

        Result

        PingOne populates the schema extension data as the value of the user attribute in PingOne, such as 100 for courseId. You can find a sample response in the Microsoft Entra documentation.

        The user attribute in PingOne must have Type set to STRING, and Multi-valued can be set to Yes or No. Learn more in Viewing user attributes.

      • Multi-valued attribute: To map a schema extension and all of its properties to a PingOne user attribute, use the following format:

        providerAttributes.<id>

        where <id> is the ID of the schema extension in the Microsoft Entra admin center.

        Example:

        For a schema extension named graphLearnCourses, Microsoft Entra returns an ID for the schema extension of extkmpdyld2_graphLearnCourses in the response. This ID is used in the expression in PingOne as follows:

        providerAttributes.extkmpdyld2_graphLearnCourses

        Result

        PingOne populates all properties for this schema extension as the values of this user attribute in PingOne, such as 100, Explore Microsoft Graph, and Online from the sample response in the Microsoft Entra documentation.

        The user attribute in PingOne must have Type set to STRING and Multi-valued set to Yes. Learn more in Viewing user attributes.

        PingOne identity data limits for custom attributes apply when adding multiple user attributes. Learn more in Standard platform limits.

  4. Click Save.

  5. On the Attributes tab, click Save.