Others

How to Customize Microsoft Entra Cloud Sync Username Mapping

Natalie Taylor Sep 30, 2026 868 views

Question details

The user needs to configure Microsoft Entra Cloud Sync to map local Active Directory attributes correctly, ensuring existing Microsoft 365 usernames are preserved instead of being overwritten by local account-name formats.

How to Customize Microsoft Entra Cloud Sync Username Mapping

Product: Microsoft Entra
Device & OS: not provided
Scenario: Syncing local Active Directory users to Microsoft Entra while preserving the specific user@domain.com Microsoft 365 username format.
Observed behavior: When linking existing users or syncing new ones, the system defaults to the local AD format, overwriting or failing to link the desired Microsoft 365 cloud usernames.

Before you start

Ensure you have Global Administrator or Hybrid Identity Administrator privileges in Microsoft Entra and have a non-production test user available in your local Active Directory to validate mappings before organization-wide deployment.

Solution 1Recommended

Modify Attribute Mapping in Microsoft Entra Admin Center

Adjust the default attribute mapping rule to directly map the local AD 'userPrincipalName' to the Entra 'email' or cloud username attribute.

By default, Entra Cloud Sync might use the local SAMAccountName or a local routing address. A direct mapping from the local userPrincipalName to the cloud email attribute often resolves formatting conflicts if the values match.

Access Entra Cloud Sync

Sign in to the Microsoft Entra admin center. Browse to Identity > Hybrid management > Microsoft Entra Connect > Cloud sync.

Open Configuration Mappings

Select your specific sync configuration under 'Agent configuration'. Under the 'Manage attributes' section, click on 'Click to edit mapping'.

Edit the Target Attribute

Locate the mapping for the cloud username or email. Change the source attribute to 'userPrincipalName' (or your desired local AD attribute) and apply the changes.

Test with On-Demand Provisioning

Before rolling out the change, navigate to 'Provision a user'. Enter the distinguished name (DN) of a test user and click 'Provision' to verify that the username maps correctly without altering production accounts.

Modify Attribute Mapping in Microsoft Entra Admin Center

Best Practice: Always validate attribute changes on a single user in a non-production environment. Once verified, you can confidently apply the mapping to the wider directory.

Solution 2

Manually Link Existing Entra Users via Immutable IDs

Use this solution if Cloud Sync successfully provisions new users but fails to link existing cloud-only users to their local Active Directory counterparts.

Free Microsoft Office alternative

Empower Your Synced Workforce with WPS Office

While you use Microsoft Entra Cloud Sync to manage user identities, providing efficient and cost-effective productivity tools to your workforce is just as crucial. WPS Office offers an outstanding, free alternative to Microsoft Office. It easily integrates into enterprise environments, ensuring your seamlessly synced users have the tools they need to succeed.

1. Download the Installer: Visit the official WPS Office website and download the free installer for your operating system.
2. Deploy to Users: Run the quick installation process or deploy the software silently across your organization's endpoints.
3. Open and Edit: Users can immediately begin opening, editing, and saving their existing Microsoft Office documents without any formatting loss.

Fully compatible with Microsoft Office formats including .docx, .xlsx, and .pptx.Lightweight installer that dramatically reduces deployment time and hardware overhead.Familiar tabbed interface requiring no retraining for employees migrating from MS Office.Cost-effective enterprise solution that reduces overall software licensing budgets.

microsoft office alternative - wps office

Frequently Asked Questions

Why does Microsoft Entra Cloud Sync overwrite my cloud usernames?

This happens when the default attribute mapping pushes the local Active Directory account-name format (such as SAMAccountName) to the cloud. Customizing the attribute mapping to point to the local 'userPrincipalName' or 'mail' attribute prevents the system from overwriting the desired cloud username.

How can I safely test Entra Cloud Sync attribute changes?

You should use the 'Provision a user' (on-demand provisioning) feature located in the Entra Cloud Sync admin center. This allows you to select a single local AD user by their Distinguished Name (DN) and simulate the sync process to verify the attribute mapping changes before applying them to the entire directory.

What is the difference between soft matching and hard matching in Entra?

Soft matching attempts to link a local AD user to a cloud user based on matching attributes like userPrincipalName or email address. Hard matching forces the link by manually assigning the local user's ObjectGUID (converted to a Base64 ImmutableID) directly to the cloud user object.

Can I map userPrincipalName directly to email?

Yes, if the local AD userPrincipalName matches the exact email address format required in Microsoft 365, a direct mapping from userPrincipalName to the cloud email attribute will work perfectly to preserve the username format.

Office Quick Solutions