KB489336: Configure Primary User Identifier in Teams Add-Ins

Introduction

Starting from version 25.06, support has been introduced to allow the use of Email or a custom user identifier for Teams SSO login. In Workstation → Add-ins → Library for Teams Add-in, a new option called Primary User Identifier has been added under Authentication Settings.

Steps

This setting provides three options:

• Preferred User Name (default)
• Email
• Custom

Note: This setting only applies to Teams SSO login.

Below are the detailed steps to configure Email or custom user identifier in Workstation Teams Add-in section.

Configure Email as Primary User Identifier

Follow the steps below to set Email as the Primary User Identifier in the Workstation Teams Add-in:

1. In Workstation, navigate to Add-ins → Library for Teams Add-in.
2. Under Authentication Settings, locate the Primary User Identifier option.
3. Expand the dropdown list next to Primary User Identifier.
4. Select Email.
5. Click Update Library Configuration to apply the changes.

Configure Custom User Identifier

Follow the steps below to set a custom user identifier in the Workstation Teams Add-in:

1. In Workstation, navigate to Add-ins → Library for Teams Add-in.
2. Under Authentication Settings, locate the Primary User Identifier option.
3. Expand the dropdown list next to Primary User Identifier.
4. Select Custom.
5. In the newly displayed input field, enter the desired custom user identifier.
6. Click Update Library Configuration to apply the changes.

Additional Notes

After completing the above configuration, the changes take effect immediately. There is no need to re-upload the Teams Add-in package to Teams.

In addition to the configuration on the Strategy Library side, corresponding settings must also be configured in the Azure portal to ensure that the correct user claim information is included in the authentication token during Azure login.

To use Email as the Primary User Identifier, you must configure the email claim in both API Permissions and Token Configuration.

Configure API Permissions

1. In the Azure portal, open your App Registration
2. Navigate to API Permissions
3. Click Add a permission → Microsoft Graph → Delegated permissions.
4. Search for email and select it.
5. Click Grant admin consent to apply the permission.

Configure Token Configuration

1. In the Azure portal, open your App Registration.
2. Navigate to the Token configuration tab.
3. Click Add optional claim.
4. Select Access token, check email, and click Add.
5. Repeat the same step for ID token, and check email to add it.

After completing these steps, the email claim will be included in both the Access token and ID token.

If using Custom identifier, you need to have this customized user claim configured in Azure portal as well.

Example: Configure Custom User Identifier (sAMAccountName)

When using a Custom user identifier, ensure that the corresponding claim is properly configured in the Azure portal. Below is a real customer scenario for reference.

Scenario

The issue occurred because the customer configured sAMAccountName as the trust ID. However, by default, the Microsoft Teams ID token does not include this claim. As a result, Library could not match the user when performing trust-based authentication.

Recommended Configuration

To use sAMAccountName as the Primary User Identifier, complete the following steps:

1. In Microsoft Entra ID, open the App Registration for the Teams application.
2. Navigate to Managed application in local directory.

3. Go to Manage → Single sign-on → Attributes & Claims and click Edit.

4. Add a new custom claim:

Name: samAccountName

Source attribute: user.onpremisessamaccountname

5. Return to the App Registration and open the application manifest (Azure AD Graph format).

6. Set the following property:

"acceptMappedClaims": true

7. In the Library Teams plugin:

Set Primary User Identifier to Custom

Enter samAccountName as the value

8. Retry signing in from the Library Teams app (either desktop or web) to force a new token to be issued.

Expected Result

The Teams ID token should include a claim similar to:

Library will then be able to use this value as the Primary User Identifier to successfully resolve and authenticate the user.

Additional Note on Configuration Changes

When switching the Primary User Identifier in Workstation and updating the Library configuration, the changes will take effect on the next login.

Since there is no logout option available in the Teams Library app, you may need to wait for the session to time out in the Teams desktop client before the changes take effect.

Alternatively, if you are using the Teams web app, you can clear the browser cookies to force a new login immediately and apply the updated configuration.

Reference: Customize app JSON Web Token (JWT) claims - Microsoft identity platform and Understanding the app manifest (Azure AD Graph format) - Microsoft identity platform