Configurar a Origem da Autoridade do Grupo (SOA)

Este artigo explica os pré-requisitos e as etapas para configurar a SOA (Fonte de Grupo de Autoridade), como reverter alterações e limitações. Para obter mais informações sobre o Grupo SOA, consulte Adotar a postura de primeira nuvem: Converter fonte de autoridade do grupo para a nuvem.

Pré-requisitos

Requisito	Descrição
Funções	O Administrador Híbrido é necessário para chamar as APIs do Microsoft Graph para ler e atualizar SOA de grupos. O Administrador de Aplicativos ou Administrador de Aplicativos na Nuvem é necessário para conceder consentimento do usuário às permissões necessárias ao Microsoft Graph Explorer ou ao aplicativo usado para chamar as APIs do Microsoft Graph.
Permissões	Para aplicativos que chamam a API onPremisesSyncBehavior do Microsoft Graph, o escopo de permissão Group-OnPremisesSyncBehavior.ReadWrite.All precisa ser concedido. Para obter mais informações, confira como conceder essa permissão ao Explorador do Graph ou a um aplicativo existente em seu locatário.
Licença necessária	Licença do Microsoft Entra Free.
Sincronizar cliente	Antes de aplicar o SOA, verifique se você está em uma versão com suporte do cliente de sincronização para que o cliente cumpra a configuração do SOA. Se você usar o Connect Sync, atualize para a versão mínima 2.5.76.0. Se você usar o Cloud Sync, atualize para a versão mínima 1.1.1370.0.
Provisionamento para o AD DS (opcional)	Para provisionar um grupo convertido SOA do Microsoft Entra ID para o Active Directory Domain Services (AD DS), você precisa usar o Cloud Sync. Você também precisa concluir as etapas para preparar os grupos para provisionamento no AD DS com o caminho original da OU. Para obter mais informações, consulte Preparar grupos para conversão e provisionamento de Grupo SOA.

Baixar o cliente de Sincronização do Connect

Baixe o build do Connect Sync versão 2.5.76.0 ou posterior.
Acesse Programas no Painel de Controle e confirme a versão do Microsoft Entra Connect Sync.

Baixar o cliente de Sincronização de Nuvem

Baixe o build do Cloud Sync versão 1.1.1370.0 ou posterior.
Saiba como identificar a versão atual do agente.
Siga as instruções para configurar o provisionamento do AD DS para a ID do Microsoft Entra.

Conceder permissão a aplicativos

Você pode conceder permissão no Centro de administração do Microsoft Entra ou no Explorador do Graph. Essa operação altamente privilegiada requer a função Administrador de Aplicativos ou Administrador de Aplicativos na Nuvem. Você também pode conceder consentimento usando o PowerShell. Para obter mais informações, consulte Conceder consentimento em nome de um único usuário.

Aplicativos personalizados

Siga estas etapas para conceder Group-OnPremisesSyncBehavior.ReadWrite.All permissão ao aplicativo correspondente. Para obter mais informações sobre como adicionar novas permissões ao registro do aplicativo e conceder consentimento, consulte Atualizar as permissões solicitadas de um aplicativo na ID do Microsoft Entra.

Usar o Centro de administração do Microsoft Entra para conceder permissão aos aplicativos

Entre no Centro de administração do Microsoft Entra como administrador de aplicativos ou administrador de aplicativos na nuvem.
Navegue até o>.
Selecione Permissões>Conceder consentimento do administrador para o nome do locatário.
Entre novamente como administrador de aplicativos ou administrador de aplicativos na nuvem.
Examine a lista de permissões que exigem seu consentimento e selecione Aceitar.
Você pode ver a lista de permissões concedidas:

Usar o Explorador do Graph para conceder permissão a aplicativos

Abra o Explorador do Graph e entre como Administrador de Aplicativos ou Administrador de Aplicativos na Nuvem.
Selecione o ícone de perfil e selecione Consentimento para permissões.
Pesquise group-OnPremisesSyncBehavior e selecione Consentimento para a permissão.

Preparar grupos para conversão e provisionamento de SOA de grupo

Se você quiser provisionar o grupo de volta ao AD DS, planeje concluir as seguintes etapas para preservar o caminho da OU e defini-lo na configuração de Provisionamento de Grupo para AD com o mapeamento adequado:

Altere o escopo do grupo para os grupos do AD DS para Universal.
Crie uma propriedade de extensão de diretório com escopo de inquilino para grupos.
Mapeie um valor local, como o DN (nome diferenciado), diretamente na propriedade de extensão.
Verifique o valor da propriedade usando o Microsoft Graph.
Converta a Origem de Autoridade (SOA) quando você estiver pronto.
Use expressões personalizadas para garantir que a Sincronização de Nuvem provisiona os grupos de volta ao AD DS com os mesmos valores de CN e OU.

Para obter mais informações, consulte Provisionar grupos para o Active Directory Domain Services usando o Microsoft Entra Cloud Sync.

Converter SOA para um grupo de teste

Siga estas etapas para converter o SOA para um grupo de teste:

Crie um grupo de segurança ou um grupo de distribuição habilitado para email no AD para testar e adicionar membros do grupo. Você também pode usar um grupo sincronizado com a ID do Microsoft Entra usando o Connect Sync.
Execute o seguinte comando para iniciar a Sincronização de Conexão:
```
Start-ADSyncSyncCycle
```
Verifique se o grupo aparece no Centro de administração do Microsoft Entra como um grupo sincronizado.
Use a API do Microsoft Graph para converter o SOA do objeto de grupo (isCloudManaged=true). Abra o Microsoft Graph Explorer e entre com uma função de usuário apropriada, como administrador de grupos.
Vamos verificar o status soa existente. Ainda não atualizamos o SOA, portanto, o valor do atributo isCloudManaged deve ser falso. Substitua o {ID} nos exemplos a seguir pela ID do objeto do seu grupo. Para obter mais informações sobre essa API, consulte Get onPremisesSyncBehavior.
```
GET https://graph.microsoft.com/v1.0/groups/{ID}/onPremisesSyncBehavior?$select=isCloudManaged
```
Confirme se o grupo sincronizado é somente leitura. Como o grupo é gerenciado localmente, todas as tentativas de gravação para o grupo na nuvem falham. A mensagem de erro é diferente para grupos habilitados para email, mas as atualizações ainda não são permitidas.

Observação

Se essa API falhar com o 403, use a guia Modificar permissões para conceder consentimento à permissão Group.ReadWrite.All necessária.
```
PATCH https://graph.microsoft.com/v1.0/groups/{ID}/
   {
     "DisplayName": "Group1 Name Updated"
   }   
```
Pesquise o centro de administração do Microsoft Entra para o grupo. Verifique se todos os campos de grupo estão esmaeçados e se essa origem é o AD DS do Windows Server:
Agora você pode atualizar o SOA do grupo para ser gerenciado na nuvem. Execute a operação a seguir no Microsoft Graph Explorer para o objeto de grupo que você deseja converter na nuvem. Para obter mais informações sobre essa API, consulte Update onPremisesSyncBehavior.
```
PATCH https://graph.microsoft.com/v1.0/groups/{ID}/onPremisesSyncBehavior
   {
     "isCloudManaged": true
   }   
```

Para validar a alteração, chame GET para verificar se isCloudManaged é verdadeiro.

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

Captura de tela da chamada GET para verificar as propriedades do grupo.

Confirme a alteração nos Logs de Auditoria. Para acessar logs de auditoria no portal do Azure, abra GerenciarLogs de Auditoria de> de > do Microsoft Entra ou pesquise logs de auditoria. Selecione Alterar Fonte de Autoridade do AD para a nuvem como a atividade.

Verifique se o grupo pode ser atualizado na nuvem.

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

Captura de tela de uma nova tentativa de alterar as propriedades do grupo.

Abra o Centro de administração do Microsoft Entra e confirme se a propriedade de origem do grupo é Cloud.

Conectar cliente de sincronização

Execute o seguinte comando para iniciar a Sincronização de Conexão:
```
Start-ADSyncSyncCycle
```
Para examinar o objeto de grupo com SOA convertido, no Gerenciador de Serviços de Sincronização, acesse Conectores:
Clique com o botão direito do mouse no Conector do Active Directory Domain Services. Pesquise o grupo pela configuração rdn (nome de domínio relativo) "CN=<GroupName>":
Dê um clique duplo na entrada pesquisada e selecione Linhagem>Propriedades de Objeto do Metaverso.
Selecione Conectores e clique duas vezes no objeto Entra ID com "CN={<Caracteres Alfanuméricos>} ".
Você pode ver que a propriedade blockOnPremisesSync está definida como true no objeto Entra ID. Esse valor de propriedade significa que todas as alterações feitas no objeto AD DS correspondente não fluem para o objeto Entra ID:
Vamos atualizar o objeto de grupo local. Alteraremos o nome do grupo de SecGroup1 para SecGroup1.1:
Execute o seguinte comando para iniciar a Sincronização de Conexão:
```
Start-ADSyncSyncCycle
```
Abra o visualizador de eventos e filtre o log de aplicativos para a ID do evento 6956. Essa ID de evento é reservada para informar aos clientes que o objeto não está sincronizado com a nuvem porque o SOA do objeto está na nuvem.

Atualizações em massa para o SOA do grupo

Você pode usar o script do PowerShell a seguir para automatizar as atualizações soa do grupo usando a autenticação baseada em aplicativo.

<#
.SYNOPSIS
    Updates groups to set isCloudManaged parameter to true for on-premises synchronized groups.

.DESCRIPTION
    This script reads a file containing group Ids, checks each group's OnPremisesSyncEnabled property,
    and if true, calls the onPremisesSyncBehavior API to set isCloudManaged to true.

.PARAMETER FilePath
    Mandatory. Path to the file containing group Ids (one per line).

.PARAMETER WhatIf
    Boolean parameter. When true (default), shows what would be done without making actual changes.

.EXAMPLE
    .\Update-GroupSoA.ps1 -FilePath "C:\temp\groups.txt"
    .\Update-GroupSoA.ps1 -FilePath "C:\temp\groups.txt" -WhatIf $false

.NOTES
    Requires Microsoft.Graph PowerShell module to be installed and appropriate permissions.
    Required Graph permissions: Group.ReadWrite.All, Group-OnPremisesSyncBehavior.ReadWrite.All

    Input file should contain one group Id (GUID) per line.
#>

[CmdletBinding()]
param(
    [Parameter(Mandatory = $true)]
    [string]$FilePath,

    [Parameter(Mandatory = $false)]
    [bool]$WhatIf = $true
)

# Import Groups module
try {
    $moduleName = "Microsoft.Graph.Groups"
    if (-not (Get-Module -Name $moduleName)) {
        Import-Module -Name $moduleName
    }
    Write-Host "Successfully imported Microsoft Graph modules."
}
catch {
    Write-Error "Failed to import Microsoft Graph modules. Please ensure Microsoft.Graph PowerShell SDK is installed."
    Write-Host "Install with: Install-Module Microsoft.Graph -Scope CurrentUser"
    exit 1
}

# Connect to MS Graph
$context = Get-MgContext
if (-not $context) {
    Connect-MgGraph -Scopes 'Group.ReadWrite.All', 'Group-OnPremisesSyncBehavior.ReadWrite.All'
}

# Validate input file
if (-not (Test-Path $FilePath)) {
    Write-Error "Input file not found: $FilePath"
    exit 1
}

Write-Host "Starting group update process using $FilePath (WhatIf: $WhatIf)..."
Write-Host "-----------------------------------"

# Read group Ids from file
$groupGuids = Get-Content $FilePath

if ($groupGuids.Count -eq 0) {
    Write-Error "No group Ids found in the input file."
    exit 1
}

Write-Host "Found $($groupGuids.Count) group Ids to process."

# Initialize counters for summary
$totalGroups = $groupGuids.Count
$processedCount = 0
$updatedCount = 0
$skippedCount = 0
$errorCount = 0

# Process each group
foreach ($groupId in $groupGuids) {
    $processedCount++
    Write-Host "`nProcessing $groupId ($processedCount/$totalGroups)"

    try {
        $group = Get-MgGroup -GroupId $groupId -Property "Id,DisplayName,OnPremisesSyncEnabled"

        Write-Host "Group Name: $($group.DisplayName)"
        Write-Host "OnPremisesSyncEnabled: $($group.OnPremisesSyncEnabled)"

        if ($group.OnPremisesSyncEnabled -eq $true) {
            $actionDescription = "Set isCloudManaged to true for group '$($group.DisplayName)'"

            if ($WhatIf) {
                Write-Host "Skipping since WhatIf is enabled: $actionDescription"
                $skippedCount++
            }
            else {
                try {
                    # Call the onPremisesSyncBehavior API to set isCloudManaged to true
                    $body = @{
                        isCloudManaged = $true
                    }

                    $uri = "https://graph.microsoft.com/v1.0/groups/$groupId/onPremisesSyncBehavior"
                    Invoke-MgGraphRequest -Uri $uri -Method PATCH -Body ($body | ConvertTo-Json) -ContentType "application/json"

                    Write-Host "SUCCESS: Updated group to cloud-managed"
                    $updatedCount++
                }
                catch {
                    Write-Host "ERROR: Failed to update group: $_"
                    $errorCount++
                }
            }
        }
        else {
            Write-Host "SKIPPED: Group is not on-premises synchronized"
            $skippedCount++
        }
    }
    catch {
        Write-Host "ERROR: Failed to retrieve group information: $_"
        $errorCount++
    }
}

Write-Host "`n-----------------------------------"
Write-Host "SUMMARY"
Write-Host "-----------------------------------"
Write-Host "Total groups processed: $totalGroups"
Write-Host "Successfully updated: $updatedCount"
Write-Host "Skipped (not sync-enabled or WhatIf): $skippedCount"
Write-Host "Errors encountered: $errorCount"

Write-Host "`nScript completed."

Status dos atributos depois de converter SOA

A tabela a seguir explica o status dos atributos isCloudManaged e onPremisesSyncEnabled depois de converter o SOA de um objeto.

Etapa de administrador	valor isCloudManaged	valor onPremisesSyncEnabled	Descrição
O administrador sincroniza um objeto do AD DS com a ID do Microsoft Entra	`false`	`true`	Quando um objeto é originalmente sincronizado com a ID do Microsoft Entra, o atributo onPremisesSyncEnabled é definido `true` como e isCloudManaged é definido como `false`.
O administrador converte a origem da autoridade (SOA) do objeto na nuvem	`true`	`null`	Depois que um administrador converte o SOA de um objeto na nuvem, o atributo isCloudManaged se torna definido `true` e o valor do atributo onPremisesSyncEnabled é definido `null`como .
O administrador reverte a operação SOA	`false`	`null`	Se um administrador converter o SOA novamente no AD, o isCloudManaged será definido `false` como e onPremisesSyncEnabled será definido `null` até que o cliente de sincronização assuma o objeto.
O administrador cria um objeto nativo de nuvem na ID do Microsoft Entra	`false`	`null`	Se um administrador criar um novo objeto nativo de nuvem na ID do Microsoft Entra, isCloudManaged será definido `false` como e onPremisesSyncEnabled será definido como `null`.

Reverter a atualização soa

Importante

Verifique se os grupos que você reverte não têm referências de nuvem. Remova os usuários de nuvem de grupos convertidos soa e remova esses grupos de pacotes de acesso antes de reverter o grupo para o AD DS. O cliente de sincronização assume o objeto no próximo ciclo de sincronização. Para obter um script de exemplo do PowerShell para identificar e remover usuários de nuvem de grupos, consulte: Script para identificar membros de nuvem (usuários) de um grupo.

Você pode executar essa operação para reverter a atualização SOA e reverter o SOA para o local.

PATCH https://graph.microsoft.com/v1.0/groups/{ID}/onPremisesSyncBehavior
   {
     "isCloudManaged": false
   }

Captura de tela da chamada à API para reverter SOA.

Observação

A alteração do isCloudManaged permite false que um objeto do AD DS que esteja no escopo da sincronização seja assumido pelo Connect Sync na próxima vez que ele for executado. Até a próxima vez que a Sincronização de Conexão for executada, o objeto poderá ser editado na nuvem. A reversão do SOA é concluída somente depois que a chamada à API e a próxima execução agendada ou forçada do Connect Sync forem concluídas.

Validar a alteração nos Logs de Auditoria

Selecione a atividade como Desfazer alterações na Fonte de Autoridade do AD DS para a nuvem:

Captura de tela de Desfazer Alterações nos Logs de Auditoria.

Validar no cliente do Connect Sync

Execute o seguinte comando para iniciar a Sincronização de Conexão:
```
Start-ADSyncSyncCycle
```
Abra o objeto no Gerenciador do Servidor de Sincronização (os detalhes estão na seção Conectar Cliente de Sincronização ). Você pode ver que o estado do objeto conector da ID do Microsoft Entra está aguardando confirmação de exportação e blockOnPremisesSync = false, o que significa que o objeto SOA é tomado pelo local novamente.

Limitações

Nenhum suporte de reconciliação para grupos do AD DS: um administrador do AD DS (ou um aplicativo com permissões suficientes) pode modificar diretamente um grupo do AD DS. Se o SOA do Grupo for convertido para o grupo ou se o provisionamento de grupo de segurança de nuvem para o AD DS estiver habilitado, essas alterações do AD local não serão refletidas na ID do Microsoft Entra. Quando uma alteração no grupo de segurança de nuvem é feita, todas as alterações locais do AD DS são substituídas quando o provisionamento de grupo para o AD DS é executado.
Nenhuma gravação dupla é permitida: depois de começar a gerenciar as associações para o grupo convertido (digamos, grupo de nuvem A) do Microsoft Entra ID, e provisionar esse grupo para o AD como um grupo aninhado em outro grupo do AD DS (OnPremGroupB) que está no escopo para sincronização para o Microsoft Entra ID, as referências de associação do grupo A não são sincronizadas quando a sincronização ocorre para o OnPremGroupB. As referências de associação não são sincronizadas porque o cliente de sincronização não sabe as referências de associação ao grupo de nuvem. Esse comportamento é por design.
Nenhuma conversão SOA de grupos aninhados: se houver grupos aninhados no AD DS e você quiser converter o SOA do grupo pai ou do grupo superior na ID do Microsoft Entra, somente o SOA do grupo pai será convertido. Os grupos aninhados no grupo pai continuam a ser grupos do AD DS. Você precisa converter o SOA de qualquer grupo aninhado um por um. Recomendamos que você comece com o grupo que é mais baixo na hierarquia e mova para cima a árvore.
Não há suporte para atributos de extensão (1 a 15): os atributos de extensão 1 a 15 não têm suporte em grupos de segurança na nuvem e não têm suporte depois que o SOA é convertido.

Script para identificar membros de nuvem (usuários) de um grupo

O script a seguir pode ser usado para identificar e remover usuários de nuvem de grupos:

<#
.SYNOPSIS
    Finds cloud users in an Entra ID group and optionally removes them.

.DESCRIPTION
    This script pages through all users in a specified Entra ID group, identifies cloud users
    (users where onPremisesSyncEnabled is not set to true), and prints their details.
    Optionally removes these users from the group if removeUsers is set to true.

.PARAMETER GroupId
    The GUID of the Entra ID group to process. This parameter is required.

.PARAMETER RemoveUsers
    Boolean flag to indicate whether to remove cloud users from the group. 
    Default is false (optional parameter).

.EXAMPLE
    .\Find-CloudUsersInGroup.ps1 -GroupId "12345678-1234-1234-1234-123456789012"
    .\Find-CloudUsersInGroup.ps1 -GroupId "12345678-1234-1234-1234-123456789012" -RemoveUsers $true

.NOTES
    Requires Microsoft.Graph PowerShell module to be installed and appropriate permissions.
    Required Graph permissions: Group.Read.All, GroupMember.Read.All, User.Read.All and GroupMember.ReadWrite.All (if removing users)
#>

[CmdletBinding()]
param(
    [Parameter(Mandatory = $true)]
    [System.Guid]$GroupId,

    [Parameter(Mandatory = $false)]
    [bool]$RemoveUsers = $false
)

# Import required modules
try {
    $moduleName = "Microsoft.Graph.Groups"
    if (-not (Get-Module -Name $moduleName)) {
        Import-Module -Name $moduleName
    }
    $moduleName = "Microsoft.Graph.Users"
    if (-not (Get-Module -Name $moduleName)) {
        Import-Module -Name $moduleName
    }
    Write-Host "Microsoft Graph modules imported successfully"
}
catch {
    Write-Error "Failed to import Microsoft Graph modules. Please install Microsoft.Graph PowerShell module."
    Write-Error "Run: Install-Module Microsoft.Graph -Scope CurrentUser"
    exit 1
}

# Connect to MS Graph and verify the group exists
$context = Get-MgContext
if (-not $context) {
    Connect-MgGraph -Scopes 'Group.Read.All','GroupMember.Read.All','GroupMember.ReadWrite.All','User.Read.All'
}

$group = Get-MgGroup -GroupId $GroupId -Property "Id,DisplayName,MailEnabled"
Write-Host "Processing group: $($group.DisplayName) (ID: $GroupId)"

if ($group.MailEnabled -eq $true) {
    Write-Warning "The specified group is mail-enabled. Users can only be identified using this script. To remove users, use Exchange."
}

# Initialize counters
$totalUsers = 0
$cloudUsers = 0
$removedUsers = 0

Write-Host "`nStarting to process group users..."

try {
    # Get all group members that are users
    $usersInGroup = Get-MgGroupMemberAsUser -GroupId $GroupId -All -Property "Id"

    if ($usersInGroup.Count -ge 1) {
        $totalUsers = $usersInGroup.Count
        Write-Host "Found $totalUsers total users in the group"
    }
    else {
        Write-Host "No users found in the group"
        exit 0
    }
}
catch {
    Write-Error "Failed to retrieve group users: $($_.Exception.Message)"
    exit 1
}

Write-Host "`nProcessing each user to identify cloud users..."
Write-Host "-----------------"

# Process each user
foreach ($user in $usersInGroup) {
    try {
        # Get detailed user information
        $user = Get-MgUser -UserId $user.Id -Property "Id,DisplayName,UserPrincipalName,OnPremisesSyncEnabled"

        # Check if user is a cloud user
        $isCloudUser = -not $user.OnPremisesSyncEnabled

        if ($isCloudUser) {
            $cloudUsers++

            # Print cloud user details
            Write-Host "Cloud User Found:"
            Write-Host "  Object ID: $($user.Id)"
            Write-Host "  Display Name: $($user.DisplayName)"
            Write-Host "  User Principal Name: $($user.UserPrincipalName)"
            Write-Host "  OnPremisesSyncEnabled: $($user.OnPremisesSyncEnabled)"

            # Remove user from group if requested
            if ($RemoveUsers) {
                Remove-MgGroupMemberByRef -GroupId $GroupId -DirectoryObjectId $user.Id -ErrorAction Stop
                Write-Host "REMOVED from group"
                $removedUsers++
            }
        }
    }
    catch {
        Write-Warning "Failed to process User ID $($user.Id): $($_.Exception.Message)"
    }
}

# Summary
Write-Host "-----------------"
Write-Host "SUMMARY:"
Write-Host "-----------------"
Write-Host "Total group users processed: $totalUsers"
Write-Host "Cloud users identified: $cloudUsers"
if ($RemoveUsers) {
    Write-Host "Cloud users successfully removed: $removedUsers"
}

if ($cloudUsers -eq 0) {
    Write-Host "No cloud users found in this group."
}

Write-Host "`nScript completed."

Esse script está sendo fornecido como um exemplo e não deve ser considerado como orientação oficial sobre como identificar e remover usuários de nuvem de associações de grupo.

Definir o escopo de um grupo para operações SOA em uma Unidade Administrativa

Para definir o escopo de um grupo para operações de "Source of Authority" em uma Unidade Administrativa, execute as seguintes etapas:

Crie uma unidade a ser usada como o escopo do grupo. Para obter etapas sobre como criar uma unidade, consulte: Criar uma unidade administrativa.
Adicione o grupo como administrador de identidade híbrida dentro do escopo.
Adicione o grupo à unidade. Para obter informações sobre isso, consulte: Adicionar usuários, grupos ou dispositivos a uma unidade administrativa.
Transfira o SOA de um grupo dentro do escopo da unidade. Para obter um guia sobre como transferir o SOA de grupos, consulte: Converter SOA para um grupo de teste.

Comentários

Esta página foi útil?

Last updated on 2025-12-08