Configure Group Source of Authority (SOA) (Preview)

This article explains the prerequisites and steps to configure Group Source of Authority (SOA), how to revert changes, and limitations. For more information about Group SOA, see Embrace cloud-first posture: Convert Group 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.

Grant permission to apps

You can grant permission in the Microsoft Entra admin center or in Graph Explorer. 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 Group-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 grant 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 Applications > 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:

   

Use Graph Explorer to grant permission to apps

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 Group-OnPremisesSyncBehavior, and select Consent for the permission.

Convert SOA for a test group

Follow these steps to convert the SOA for a test group:

1. Create a security group or a mail-enabled distribution group in AD for testing and add group members. You can also use a group 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 group appears in the Microsoft Entra admin center as a synced group.

4. Use Microsoft Graph API to convert the SOA of the group object (isCloudManaged=true). Open Microsoft Graph Explorer and sign in with an appropriate user role, such as Groups 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 group. For more information about this API, see Get onPremisesSyncBehavior.

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

   

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

   Note

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

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

   

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

   

   

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

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

   

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

   GET https://graph.microsoft.com/beta/groups/{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 group can be updated in the cloud.

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

    

12. Open Microsoft Entra admin center and confirm that the group Source property is Cloud.

    

Connect Sync client

1. Run the following command to start Connect Sync:

   Start-ADSyncSyncCycle
   

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

   

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

   

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

   

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

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

   

7. Let’s update the on-premises group object. We'll change the group name from SecGroup1 to SecGroup1.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.

   

Bulk updates for Group SOA

You can use the following PowerShell script to automate Group SOA updates by using app-based authentication.

# Define your Microsoft Entra ID app details and tenant information
$tenantId = ""
$clientId = ""
$certThumbprint = ""

# Connect to Microsoft Graph as App-Only using a certificate. The app registration must have the Group.Read.All Group-OnPremisesSyncBehavior.ReadWrite.All permissions granted.
Connect-MgGraph -ClientId $clientId -TenantId $tenantId -CertificateThumbprint $certThumbprint

#Connect to Microsoft Graph using delegated permissions
#Connect-MgGraph -Scopes "Group.Read.All Group-OnPremisesSyncBehavior.ReadWrite.All" -TenantId $tenantId

# Define the group name you want to query
$groupName = "HR India"

# Retrieve the group using group name
$group = Get-MgBetaGroup -Filter "displayName eq '$groupName'"

# Ensure group is found
if ($null -ne $group)
{
    $groupObjectID = $($group.Id)
    # Define the Microsoft Graph API endpoint for the group
    $url = "https://graph.microsoft.com/beta/groups/$groupObjectID/onPremisesSyncBehavior"

    # Define the JSON payload for the PATCH request
    $jsonPayload = @{
        isCloudManaged = "true"
    } | ConvertTo-Json

    # Make the PATCH request to update the JSON payload
    Invoke-MgGraphRequest -Uri $url -Method Patch -ContentType "application/json" -Body $jsonPayload

    $result = Invoke-MgGraphRequest -Method Get -Uri "https://graph.microsoft.com/beta/groups/$groupObjectID/onPremisesSyncBehavior?`$select=id,isCloudManaged"

    Write-Host "Group Name: $($group.DisplayName)"
    Write-Host "Group ID: $($result.id)"
    Write-Host "SOA Converted: $($result.isCloudManaged)"
}
else 
{
    Write-Warning "Group '$groupName' not found."
}

Status of attributes after you convert SOA

The following table explains the status for isCloudManaged and onPremisesSyncEnabled attributes after you convert 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/groups/{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.

   

Limitations

• No reconciliation support for local AD groups: An AD DS admin (or an application with sufficient permissions) can directly modify an AD DS group. If Group SOA is converted for the group, or if cloud security group provisioning to AD DS is enabled, those local AD changes aren't reflected in Microsoft Entra ID. When a change to the cloud security group is made, any local AD DS changes are overwritten when group provisioning to AD DS runs.

• No dual write allowed: After you start to manage the memberships for the converted group (say cloud group A) from Microsoft Entra ID, and you provision this group to AD as a nested group under another AD DS group (OnPremGroupB) that's in scope for sync to Microsoft Entra ID, the membership references of group A aren't synced when sync happens for OnPremGroupB. The membership references aren't synced because the sync client doesn't know the cloud group membership references. This behavior is by design.

• No SOA conversion of nested groups: If there are nested groups in AD DS, and you want to convert the SOA of the parent group or top group to Microsoft Entra ID, only the parent group SOA is converted. Nested groups in the parent group continue to be AD DS groups. You need to convert the SOA of any nested groups one-by-one. We recommend you start with the group that is lowest in the hierarchy, and move up the tree.

• No support for extension attributes (1-15): Extension attributes 1–15 aren't supported on cloud security groups and aren't supported after SOA is converted.

Related content

• Group SOA overview
• Provision groups to Active Directory Domain Services by using Microsoft Entra Cloud Sync
• onPremisesSyncBehavior Microsoft Graph API