Configure user Source of Authority (SOA) (Preview)

This article explains the prerequisites, and steps, to configure User Source of Authority (SOA). This article also explains how to revert changes, and current feature limitations. For a full overview for User SOA, see Embrace cloud-first posture: Transfer User Source of Authority to the cloud (Preview).

Prerequisites

Setup

You need to set up Connect Sync client and the Microsoft Entra Provisioning agent.

Connect sync client

1. Download the latest version of the Connect Sync build.

2. Verify the Connect Sync build is successfully installed. Go to Programs in Control Panel and confirm that the version of Microsoft Entra Connect Sync is 2.5.76.0.

Cloud sync client

Download the Microsoft Entra Provisioning agent with build version 1.1.1370.0 or later.

1. Follow the instructions to download the Cloud Sync client.

2. Learn how to identify the agent's current version.

3. Follow the instructions to configure provisioning from AD DS to Microsoft Entra ID.

Consent permission to apps

You can consent permission in the Microsoft Entra admin center. This highly privileged operation requires the Application Administrator or Cloud Application Administrator role. You can also grant consent by using PowerShell. For more information, see Grant consent on behalf of a single user.

Custom apps

Follow these steps to grant User-OnPremisesSyncBehavior.ReadWrite.All permission to the corresponding app. For more information about how to add new permissions to your app registration and grant consent, see Update an app's requested permissions in Microsoft Entra ID.

Use Microsoft Entra admin center to consent permission to apps

1. Sign in to the Microsoft Entra admin center as an Application Administrator or a Cloud Application Administrator.

2. Browse to Enterprise Apps > App name.

3. Select Permissions > Grant admin consent for tenant name.

4. Sign in again as an Application Administrator or a Cloud Application Administrator.

5. Review the list of permissions that require your consent, and select Accept.

6. You can see the list of permissions that you granted:

Grant permission to Graph Explorer

1. Open Graph Explorer and sign in as an Application Administrator or Cloud Application Administrator.

2. Select the profile icon, and select Consent to permissions.

3. Search for User-OnPremisesSyncBehavior, and select Consent for the permission.

Transfer SOA for a test user

Follow these steps to transfer the SOA for a test user:

1. Create a user within AD. You can also use an existing user that is synced to Microsoft Entra ID by using Connect Sync.

2. Run the following command to start Connect Sync:

   Start-ADSyncSyncCycle
   

3. Verify that the user appears in the Microsoft Entra admin center as a synced user.

4. Use Microsoft Graph API to transfer the SOA of the user object (isCloudManaged=true). Open Microsoft Graph Explorer and sign in with an appropriate user role, such as user admin.

5. Let's check the existing SOA status. We didn’t update the SOA yet, so the isCloudManaged attribute value should be false. Replace the {ID} in the following examples with the object ID of your user. For more information about this API, see Get onPremisesSyncBehavior. /graph/api/onpremisessyncbehavior-update

   GET https://graph.microsoft.com/beta/users/{ID}/onPremisesSyncBehavior?$select=isCloudManaged
   

   

6. Confirm that the synced user is read-only. Because the user is managed on-premises, any write attempts to the user in the cloud fail. The error message differs for mail-enabled users, but updates still aren't allowed.

   Note

   If this API fails with 403, use the Modify permissions tab to grant consent to the required User.ReadWrite.All permission.

   PATCH https://graph.microsoft.com/v1.0/users/{ID}/
      {
        "DisplayName": "User Name Updated"
      }   
   

   

7. Search the Microsoft Entra admin center for the user. Verify that all user fields are greyed out, and that source is Windows Server AD DS.

8. Now you can update the SOA of the user to be cloud-managed. Run the following operation in Microsoft Graph Explorer for the user object you want to transfer to the cloud. For more information about this API, see Update onPremisesSyncBehavior.

   PATCH https://graph.microsoft.com/beta/users/{ID}/onPremisesSyncBehavior
      {
        "isCloudManaged": true
      }   
   

   

9. To validate the change, call GET to verify isCloudManaged is true.

   GET https://graph.microsoft.com/beta/users/{ID}/onPremisesSyncBehavior?$select=isCloudManaged
   

   

10. Confirm the change in the Audit Logs. To access Audit Logs in the Azure portal, open Manage Microsoft Entra ID > Monitoring > Audit Logs, or search for audit logs. Select Change Source of Authority from AD to cloud as the activity.

11. Check that the user can be updated in the cloud.

    PATCH https://graph.microsoft.com/v1.0/users/{ID}/
       {
         "DisplayName": "Update User Name"
       }   
    

    

12. Open Microsoft Entra admin center and confirm that the user On-premises sync enabled property is Yes.

Connect Sync client

1. Run the following command to start Connect Sync:

   Start-ADSyncSyncCycle
   

2. To look at the user object with transferred SOA, in the Synchronization Service Manager, go to Connectors:

   

3. Right-click Active Directory Domain Services Connector. Search for the user by the relative domain name (RDN) setting "CN=<UserName>":

   

4. Double-click the searched entry, and select Lineage > Metaverse Object Properties.

   

5. Select Connectors and double-click the Microsoft Entra ID object with "CN={<Alphanumeric Characters>}".

6. You can see that the blockOnPremisesSync property is set to true on the Microsoft Entra ID object. This property value means that any changes made in the corresponding AD DS object don't flow to the Microsoft Entra ID object:

   

7. Let’s update the on-premises user object. We change the user name from TestUserF1 to TestUserF1.1:

   

8. Run the following command to start Connect Sync:

   Start-ADSyncSyncCycle
   

9. Open Event viewer and filter the Application log for event ID 6956. This event ID is reserved to inform the customers that the object isn't synced to the cloud because the SOA of the object is in the cloud.

   

Status of attributes after you transfer SOA

The following table explains the status for isCloudManaged and onPremisesSyncEnabled attributes after you transfer the SOA of an object.

Roll back SOA update

You can run this operation to roll back the SOA update and revert the SOA to on-premises.

PATCH https://graph.microsoft.com/beta/users/{ID}/onPremisesSyncBehavior
   {
     "isCloudManaged": false
   }   

Validate the change in the audit logs

Select activity as Undo changes to Source of Authority from AD DS to cloud:

Validate in Connect Sync client

1. Run the following command to start Connect Sync:

   Start-ADSyncSyncCycle
   

2. Open the object in the Synchronization Server Manager (details are in the Connect Sync Client section). You can see the state of the Microsoft Entra ID connector object is Awaiting Export Confirmation and blockOnPremisesSync = false, which means the object SOA is taken over by the on-premises again.

   

Clear on-premises attributes for SOA transferred users

The following are the list of on-premises properties present on the cloud user object that are used for accessing on-premises resources:

• onPremisesDistinguishedName
• onPremisesDomainName
• onPremisesSamAccountName
• onPremisesSecurityIdentifier
• onPremisesUserPrincipalName

If Admins want to access on-premises resources after transfer of SOA, you must manually maintain these attributes using Microsoft Graph, and not delete, these attributes.

Related content

• How to audit and monitor User Source of Authority (SOA) in Microsoft Entra ID (Preview)
• Configure Group Source of Authority (SOA) (Preview)