Configuration

This quickstart walks through setting up Cloud Sync from scratch: installing the provisioning agent, creating a configuration in the Entra admin center, and verifying that objects sync correctly.

Prerequisites

Before you start:

• Entra ID tenant with at least a Hybrid Identity Administrator role.
• On-premises AD domain with a domain-joined Windows Server (2016 or later) for the agent. The agent can also run on a domain controller.
• Network access from the agent server: outbound HTTPS (port 443) to *.msappproxy.net and *.servicebus.windows.net. Port 80 outbound for CRL checks. No inbound ports required.
• gMSA prerequisites. The KDS root key must be created in the domain. The agent installer creates the gMSA automatically if you have the right permissions, or you can pre-create it.

Step 1: Install the Provisioning Agent

Download the agent from the Entra admin center:

1. Sign in to the Entra admin center as a Hybrid Identity Administrator.
2. Navigate to Identity > Hybrid management > Microsoft Entra Connect > Cloud sync.
3. Select Agent > Download on-premises agent.
4. Run the installer on your domain-joined server.
5. During setup, authenticate with your Entra ID Global Administrator credentials.
6. The installer creates a gMSA and registers the agent with your tenant.

After installation, verify the agent appears in the Entra admin center with an Active status.

Tip: Install a second agent on a different server for high availability. Both agents register with the same tenant and forest, providing automatic failover.

PowerShell Installation

For automated deployments, the agent can also be installed via PowerShell:

# Silent install example
.\AADConnectProvisioningAgentSetup.exe /quiet /norestart

See the PowerShell reference for full silent install parameters.

Step 2: Create a Configuration

1. In the Entra admin center, go to Cloud sync.
2. Select New configuration.
3. Select AD to Microsoft Entra ID sync.
4. Choose your domain and whether to enable password hash sync.
5. Select Create.

The configuration opens a guided setup with five sections: scoping filters, attribute mappings, testing, default properties, and enablement.

Step 3: Configure Scoping Filters

Scoping filters determine which AD objects sync to Entra ID. Options:

• All users - sync every user in the domain (up to the 150K object limit).
• Selected security groups - sync only members of specific AD security groups. Best for pilot testing, but has limitations with nested groups and large group sizes.
• Selected organizational units - sync users in specific OUs. This is the most common production scoping approach.

For OU scoping, provide the distinguished name (e.g., OU=Sales,DC=contoso,DC=com).

Note: Nested groups are not supported with group scoping. Objects nested beyond the first level are excluded. Use OU scoping for production deployments.

Step 4: Configure Attribute Mappings

Cloud Sync comes with default attribute mappings that cover standard user attributes (displayName, mail, userPrincipalName, proxyAddresses, etc.). You can customize these:

1. Select Attribute mapping in the configuration.
2. Review the default mappings.
3. To modify a mapping, select it and change the source attribute, mapping type, or add an expression.
4. To add a new mapping, select Add attribute mapping.

Mapping types:

For complex transformations, use the expression builder. It provides a visual UI for building and testing expressions before applying them.

Directory Extensions

Cloud Sync supports syncing custom AD attributes via directory extensions (extensionAttribute1-15) and customer-defined schema extensions. Configure these under Directory extensions and custom attribute mapping in the configuration.

Step 5: Test with On-Demand Provisioning

Before enabling the full sync, test your configuration against individual objects:

1. Select Provision on demand in the configuration.
2. Enter a user’s distinguished name or search for them.
3. Select Provision.
4. Review the results to verify attribute mappings are correct.

This is a Cloud Sync feature that Connect Sync does not have. Use it to validate your configuration before it affects production objects.

Step 6: Review Default Properties

Before enabling, review the default settings:

• Accidental delete prevention. Enabled by default with a threshold of 500 objects. If a sync cycle would delete more objects than the threshold, the job is quarantined.
• Notification email. Set an email address to receive alerts when the sync job enters quarantine.

Adjust the delete threshold if your environment has legitimate bulk changes (e.g., seasonal employee turnover).

Step 7: Enable the Configuration

1. Select Review and enable.
2. Select Enable configuration.

The sync engine starts running on a 2-minute cycle. The first cycle is a full sync; subsequent cycles are delta syncs processing only changes.

Verification

After enabling:

1. Check the provisioning logs. In the Entra admin center, go to the configuration and select Provisioning logs. Verify that objects are being synced successfully.
2. Spot-check users. Find a synced user in Entra ID and verify their attributes match the on-premises values.
3. Check agent health. Verify the agent status remains Active in the Cloud sync agent list.

Common First-Sync Issues

For deeper troubleshooting, see the troubleshooting deep dive.