---
title: Selecting the attribute to identify users from username tokens
description: Select the attribute PingOne uses to identify users from username tokens in the Microsoft 365 application.
component: pingone
page_id: pingone:applications:p1_selecting_username_token_attribute
canonical_url: https://docs.pingidentity.com/pingone/applications/p1_selecting_username_token_attribute.html
section_ids:
  before-you-begin: Before you begin
  steps: Steps
  example-scenarios: Example scenarios
  example-1-using-userprincipalname-from-ad-as-the-entra-id-username-with-the-userprincipalname-and-mail-attributes-always-sharing-the-same-value: "Example 1: Using userPrincipalName from AD as the Entra ID username with the userPrincipalName and mail attributes always sharing the same value"
  attribute-selection: Attribute selection
  example-2-using-userprincipalname-from-ad-as-the-entra-id-username-and-storing-userprincipalname-from-ad-in-pingone: "Example 2: Using userPrincipalName from AD as the Entra ID username and storing userPrincipalName from AD in PingOne"
  attribute-selection-2: Attribute selection
  example-3-using-an-alternative-ad-user-attribute-as-the-entra-id-username: "Example 3: Using an alternative AD user attribute as the Entra ID username"
  attribute-selection-3: Attribute selection
---

# Selecting the attribute to identify users from username tokens

When you add a Microsoft 365 application to allow users to sign on using PingOne and use Microsoft Entra Connect Sync to sync users from Active Directory (AD) to Entra ID, you can select which user attribute PingOne uses to match user records to the username from security token service (STS) requests.

By default, the following attributes are used and matched to identify users in an STS request:

* Entra ID uses the AD `userPrincipalName` attribute as the source of the username.

* PingOne matches `userPrincipalName` from Entra ID to the email address (`mail` attribute) in the PingOne user record.

If the `userPrincipalName` attribute doesn't match the `mail` attribute, you must select an attribute for PingOne to match user records to username tokens. If PingOne can't locate a user record matching the username in the token, the STS request could fail and prevent PingOne from obtaining or renewing a primary refresh token (PRT) from Entra ID.

## Before you begin

1. [Download and install Entra Connect Sync](../use_cases/p1_microsoft_entra_hybrid_join_prerequisites.html).

2. [Set which attribute Entra ID should use for **User Principal Name**](../use_cases/p1_microsoft_entra_hybrid_join_prerequisites.html#p1-install-entra-connect-sync-upn).

3. [Add a Microsoft 365 application](p1_adding_microsoft_365.html) in PingOne.

## Steps

1. In the PingOne admin console, go to **Applications > Applications** and click the **Microsoft 365 application** in the **Applications** list.

2. If you haven't already, click **Enable Advanced Configuration** on the **Overview** tab and click **Enable** in the confirmation modal.

   ![A screenshot of Enable Advanced Configuration button on the Overview tab.](_images/p1-microsoft-365-application-enable-advanced-configuration.png)

3. On the **Configuration** tab, click the **Pencil** icon ([icon: pencil, set=fa]).

4. In the **Attribute to identify users from username tokens** list, select the attribute for PingOne to use to match the username from the STS request to an existing profile.

5. Click **Save**.

## Example scenarios

The following scenarios describe example configurations when setting up user authentication with PingOne as the federated identity provider (IdP) for Entra and which attribute to select for PingOne to match to the username in the username token.

### Example 1: Using `userPrincipalName` from AD as the Entra ID username with the `userPrincipalName` and `mail` attributes always sharing the same value

You set up the following attribute configurations:

* Kept the default mapping for **User Principal Name** to `userPrincipalName` in [Installing Microsoft Entra Connect Sync](../use_cases/p1_microsoft_entra_hybrid_join_prerequisites.html#p1-install-entra-connect-sync-upn)

* Kept the default mapping for `mail` attribute from AD to **Email Address** in PingOne when [adding an LDAP gateway user type for cloud users](../use_cases/p1_microsoft_hybrid_join_tasks.html#p1-add-ldap-gateway)

* Didn't create a custom attribute to store `userPrincipalName` in PingOne

#### Attribute selection

In this example configuration, you can select either **None** or **Email Address** if the `userPrincipalName` and `mail` attributes always share the same value.

Selecting either has the same outcome because the username in the username token is the `userPrincipalName` for the user, and PingOne can locate an existing user profile by matching the username from the token to the email address record.

### Example 2: Using `userPrincipalName` from AD as the Entra ID username and storing `userPrincipalName` from AD in PingOne

You set up the following attribute configurations:

* Kept the default mapping for **User Principal Name** to `userPrincipalName` in [Installing Microsoft Entra Connect Sync](../use_cases/p1_microsoft_entra_hybrid_join_prerequisites.html#p1-install-entra-connect-sync)

* Kept the default mapping for `mail` attribute from AD to **Email Address** in PingOne when [adding an LDAP gateway user type for cloud users](../use_cases/p1_microsoft_hybrid_join_tasks.html#p1-add-ldap-gateway)

* [Created a custom attribute](../use_cases/p1_microsoft_hybrid_join_tasks.html#p1-create-attribute) to store `userPrincipalName` in PingOne and mapped the custom attribute when [adding an LDAP gateway user type for cloud users](../use_cases/p1_microsoft_hybrid_join_tasks.html#p1-add-ldap-gateway)

#### Attribute selection

* If the `userPrincipalName` and `mail` attributes always share the same value, you can select **None**. You can alternatively select **Email Address** or the custom attribute you created to store `userPrincipalName` in PingOne.

  Selecting any of these has the same outcome because the username in the username token is the `userPrincipalName` for the user, and PingOne can locate an existing user profile by matching the username from the token to the selected attribute.

* If the `userPrincipalName` and `mail` attributes don't always share the same value, select the custom attribute you created to store `userPrincipalName` in PingOne. PingOne can locate an existing user profile by matching the username from the token to the custom attribute.

  If you don't select the custom attribute you created, PingOne won't be able to locate the user record for any user whose `userPrincipalName` and `mail` attributes don't share the same value. This can lead to failures, such as PingOne not being able to obtain a primary refresh token (PRT) from Entra ID.

### Example 3: Using an alternative AD user attribute as the Entra ID username

You set **User Principal Name** to a different AD user attribute (not `userPrincipalName`) to use as the Entra ID username.

In this scenario, you must:

1. Create a custom user attribute in PingOne to store the AD attribute you set for **User Principal Name**. Learn more in [Creating an attribute in PingOne](../use_cases/p1_microsoft_hybrid_join_tasks.html#p1-create-attribute).

2. Map the attribute from AD to the custom attribute in PingOne in the LDAP gateway user type for your cloud users. Learn more in [Adding an LDAP gateway to connect PingOne with AD](../use_cases/p1_microsoft_hybrid_join_tasks.html#p1-add-ldap-gateway).

#### Attribute selection

Select the custom attribute you created to store the AD attribute you set for **User Principal Name** in Entra. This enables PingOne to locate an existing user profile by matching the username in the username token to this attribute.

If you don't select the custom attribute you created, PingOne won't be able to locate the user record for any user whose `userPrincipalName` and `mail` attributes don't share the same value. This can lead to failures, such as PingOne not being able to obtain a PRT from Entra ID.