Como configurar programaticamente a sincronização de nuvem usando a API do MS Graph

O documento a seguir descreve como replicar um perfil de sincronização do zero usando apenas APIs do MSGraph.
A estrutura que organiza como replicar um perfil de sincronização é formada pelas etapas a seguir. Eles são:

• Como configurar programaticamente a sincronização de nuvem com o uso da API do Graph MS
  • Configuração básica
    • Habilitar sinalizadores de locatário
  • Criar entidades de serviço
  • Criar trabalho de sincronização
  • Atualizar domínio de destino
  • Habilitar hashes de senha de Sincronização na folha de configuração
  • Write-back híbrido do Exchange
  • Exclusões acidentais
    • Habilitar e definir o limite
    • Permitir exclusões
  • Iniciar trabalho de sincronização
  • Analisar o status
  • Próximas Etapas 

Use estes comandos do PowerShell do Microsoft Graph para habilitar a sincronização em um locatário de produção, um dos pré-requisitos para chamar o Serviço Web de Administração nesse locatário.

Configuração básica

Habilitar sinalizadores de locatário

Connect-MgGraph -Scopes "DeviceManagementConfiguration.ReadWrite.All" ('-Environment <AzureEnvironment>')
$organizationId = (Get-MgOrganization).Id
$params = @{
	onPremisesSyncEnabled = $true
}
Update-MgBetaOrganization -OrganizationId $organizationId -BodyParameter $params

Esse cmdlet habilita a sincronização para um locatário. Ele usa o Get-MgOrganization para obter a ID da organização.

Criar entidades de serviço

Em seguida, precisamos criar a entidade de serviço/aplicativo AD2AAD

Você precisa usar essa identificação do aplicativo 1a4721b3-e57f-4451-ae87-ef078703ec94. O displayName é a URL de domínio do AD, se usada no portal (por exemplo, contoso.com), mas pode ter outro nome.

POST https://graph.microsoft.com/beta/applicationTemplates/1a4721b3-e57f-4451-ae87-ef078703ec94/instantiate
Content-type: application/json
{
    displayName: [your app name here]
}

Criar trabalho de sincronização

A saída do comando anterior retorna o objectId da entidade de serviço que foi criada. Neste exemplo, a objectId é aaaaaaaaa-0000-1111-2222-bbbbbbbbbbbb. Use o Microsoft Graph para adicionar um synchronizationJob à entidade de serviço.

A documentação para criar um trabalho de sincronização pode ser encontrada aqui.

Se você não registrou a ID, você poderá encontrar a entidade de serviço executando a seguinte chamada do MS Graph. Você precisa do Directory.Read.All permissions para fazer essa chamada:

GET https://graph.microsoft.com/beta/servicePrincipals

Em seguida, procure o nome do aplicativo na saída.

Execute os dois comandos a seguir para criar dois trabalhos: um para provisionamento do usuário/grupo e outro para sincronização de hash de senha. É a mesma solicitação duas vezes, mas com IDs de modelo diferentes.

Chame as duas solicitações a seguir:

POST https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs
Content-type: application/json
{
"templateId":"AD2AADProvisioning"
} 

POST https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs
Content-type: application/json
{
"templateId":"AD2AADPasswordHash"
}

Você precisa de duas chamadas se quiser criar ambas.

Exemplo de valor retornado (para provisionamento):

HTTP 201/Created
{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#servicePrincipals('aaaaaaaa-0000-1111-2222-bbbbbbbbbbbbc')/synchronization/jobs/$entity",
    "id": "AD2AADProvisioning.fc96887f36da47508c935c28a0c0b6da",
    "templateId": "ADDCInPassthrough",
    "schedule": {
        "expiration": null,
        "interval": "PT40M",
        "state": "Disabled"
    },
    "status": {
        "countSuccessiveCompleteFailures": 0,
        "escrowsPruned": false,
        "code": "Paused",
        "lastExecution": null,
        "lastSuccessfulExecution": null,
        "lastSuccessfulExecutionWithExports": null,
        "quarantine": null,
        "steadyStateFirstAchievedTime": "0001-01-01T00:00:00Z",
        "steadyStateLastAchievedTime": "0001-01-01T00:00:00Z",
        "troubleshootingUrl": null,
        "progress": [],
        "synchronizedEntryCountByType": []
    }
}

Atualizar domínio de destino

Para esse locatário, o identificador do objeto e o identificador do aplicativo da entidade de serviço são os seguintes:

ObjectId: bbbbbbbb-1111-2222-3333-cccccccccccc
AppId: 00001111-aaaa-2222-bbbb-3333cccc4444
DisplayName: testApp

Vamos precisar atualizar o domínio para o qual essa configuração está sendo direcionada, portanto, atualize os segredos para esse domínio.

Verifique se o nome de domínio usado é a mesma URL que você definiu para o controlador de domínio local.

PUT – https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/secrets

Adicione o seguinte par chave/valor à matriz de valores abaixo com base no que você está tentando fazer:

• Habilite PHS e os sinalizadores do locatário de sincronização { key: "AppKey", value: "{"appKeyScenario":"AD2AADPasswordHash"}" }

• Habilitar somente o sinalizador do locatário de sincronização (não ativar o PHS) { key: "AppKey", value: "{"appKeyScenario":"AD2AADProvisioning"}" }

Request body –
{
   "value": [
              {
                "key": "Domain",
                "value": "{\"domain\":\"ad2aadTest.com\"}"
              }
            ]
}

A resposta esperada é... HTTP 204/Sem conteúdo

Aqui, o valor de “Domínio” realçado é o nome do domínio do Active Directory local do qual as entradas devem ser provisionadas na ID do Microsoft Entra.

Habilitar hashes de senha de sincronização na folha de configuração

Esta seção aborda a habilitação de hashes de senha de sincronização para uma configuração específica. Essa situação é diferente do segredo AppKey que habilita o sinalizador de recurso no nível do locatário. Este procedimento é apenas para um único domínio/configuração. Você precisa definir a chave do aplicativo para o PHS para que esse procedimento funcione de ponta a ponta.

1. Capte o esquema (saiba que ele é muito grande):

   GET –https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs/ [AD2AADProvisioningJobId]/schema
   

2. Use este mapeamento de atributo CredentialData:

   {
   "defaultValue": null,
   "exportMissingReferences": false,
   "flowBehavior": "FlowWhenChanged",
   "flowType": "Always",
   "matchingPriority": 0,
   "targetAttributeName": "CredentialData",
   "source": {
   "expression": "[PasswordHash]",
   "name": "PasswordHash",
   "type": "Attribute",
   "parameters": []
   }
   

3. Localize os seguintes mapeamentos de objeto com os seguintes nomes no esquema

   • Provisionar Usuários do Active Directory
   • Provisionar inetOrgPersons do Active Directory

   Os mapeamentos de objeto estão dentro do schema.synchronizationRules[0].objectMappings (por enquanto, você pode supor que há apenas uma Regra de Sincronização)

4. Faça o Mapeamento de CredentialData na Etapa (2) e insira-o nos mapeamentos de objeto na Etapa (3)

   Seu mapeamento de objeto terá a seguinte aparência:

   {
   "enabled": true,
   "flowTypes": "Add,Update,Delete",
   "name": "Provision Active Directory users",
   "sourceObjectName": "user",
   "targetObjectName": "User",
   "attributeMappings": [
   ...
   } 
   

   Copie/cole o mapeamento da etapa Criar trabalhos AD2AADProvisioning e AD2AADPasswordHash na matriz attributeMappings.

   A ordem dos elementos nesta matriz não importa (o back-end classifica para você). Tenha cuidado ao adicionar esse mapeamento de atributo se o nome já existir na matriz (por exemplo, se já houver um item em attributeMappings que tenha o targetAttributeName CredentialData) –você pode receber erros de conflito, ou os mapeamentos preexistentes e novos podem ser combinados (o que geralmente não é o resultado desejado). O back-end não elimina a duplicação para você.

   Lembre-se de fazer essa ação para Usuários e inetOrgpersons.

5. Salve o esquema que você criar:

   PUT –
   https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs/ [AD2AADProvisioningJobId]/schema
   

Adicione o Esquema no corpo da solicitação.

Write-back híbrido do Exchange (Visualização Pública)

Esta seção aborda como habilitar/desabilitar e usar o write-back híbrido do Exchange programaticamente.

A habilitação do write-back híbrido do Exchange programaticamente requer duas etapas.

1. Verificação de esquema
2. Criar o trabalho de write-back híbrido do Exchange

Verificação de esquema

antes de habilitar e usar o write-back híbrido do Exchange, a sincronização de nuvem precisa determinar se o Active Directory local foi estendido ou não para incluir o esquema do Exchange.

Você pode usar o directoryDefinition:discover para iniciar a descoberta de esquema.

POST https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs/[AD2AADProvisioningJobId]/schema/directories/[ADDirectoryID]/discover

A resposta esperada é... HTTP 200/OK

A resposta será parecida com a saída a seguir:

HTTP/1.1 200 OK
Content-type: application/json
{
  "objects": [
    {
      "name": "user",
      "attributes": [
        {
          "name": "mailNickName",
          "type": "String"
        },
        ...
      ]
    },
    ...
  ]
}

Agora verifique se o atributo mailNickName está presente. Se estiver, o esquema será verificado e conterá os atributos do Exchange. Caso contrário, examine os pré-requisitos para write-back híbrido do Exchange.

Criar o trabalho de write-back híbrido do Exchange

Depois de verificar o esquema, você poderá criar o trabalho.

POST https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs
Content-type: application/json
{
"templateId":"AAD2ADExchangeHybridWriteback"
}

Exclusões acidentais

Esta seção explica como habilitar e desabilitar programaticamente e usar exclusões acidentais programaticamente.

Habilitando e definindo o limite

Há duas configurações por trabalho que você pode usar, quais sejam:

• DeleteThresholdEnabled ─ habilita a prevenção contra exclusão acidental para o trabalho, quando definido como 'true'. Definido como 'true' por padrão.
• DeleteThresholdValue – define o número máximo de exclusões permitidas em cada execução do trabalho quando a prevenção de exclusões acidentais estiver habilitada. O valor é definido como 500 por padrão. Portanto, se o valor for definido como 500, o número máximo de exclusões permitidas é de 499 em cada execução.

As configurações do limite de exclusão fazem parte do SyncNotificationSettings e podem ser modificadas através do grafo.

Vamos precisar atualizar o SyncNotificationSettings para o qual essa configuração está sendo direcionada, portanto, atualize os segredos.

PUT – https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/secrets

Adicione o seguinte par Chave/Valor na matriz de valores abaixo com base no que você está tentando fazer:

Request body -
{
  "value":[
    {
      "key":"SyncNotificationSettings",
      "value": "{\"Enabled\":true,\"Recipients\":\"foobar@xyz.com\",\"DeleteThresholdEnabled\":true,\"DeleteThresholdValue\":50}"
     }
  ]
}

A configuração "Habilitado" no exemplo serve para habilitar/desabilitar emails de notificação quando o trabalho é colocado em quarentena.

Atualmente, não oferecemos suporte para solicitações de PATCH para segredos. Portanto, será necessário adicionar todos os valores no corpo da solicitação PUT (como no exemplo) para preservar os outros valores.

Os valores existentes para todos os segredos podem ser recuperados ao usar:

GET https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/secrets 

Permitindo exclusões

Para permitir que essas exclusões fluam depois que o trabalho entrar em quarentena, você precisará emitir uma reinicialização com apenas "ForceDeletes" como o escopo.

Request:
POST https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs/{jobId}/restart

Request Body:
{
  "criteria": {"resetScope": "ForceDeletes"}
}

Iniciar trabalho de sincronização

Os trabalhos podem ser recuperados novamente através do seguinte comando:

GET https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs/

A documentação para recuperar trabalhos pode ser encontrada aqui.

Para iniciar os trabalhos, emita essa solicitação, usando o objectId da entidade de serviço criada na primeira etapa e o identificador do trabalho retornado da solicitação que criou o trabalho.

A documentação sobre como iniciar um trabalho pode ser encontrada aqui.

POST  https://graph.microsoft.com/beta/servicePrincipals/8895955e-2e6c-4d79-8943-4d72ca36878f/synchronization/jobs/AD2AADProvisioning.fc96887f36da47508c935c28a0c0b6da/start

A resposta esperada é... HTTP 204/Sem conteúdo.

Outros comandos para controlar o trabalho estão documentados aqui.

Para reiniciar um trabalho, use:

POST  https://graph.microsoft.com/beta/servicePrincipals/8895955e-2e6c-4d79-8943-4d72ca36878f/synchronization/jobs/AD2AADProvisioning.fc96887f36da47508c935c28a0c0b6da/restart
{
  "criteria": {
    "resetScope": "Full"
  }
}

Status da análise

Recupere seus status do trabalho através de:

GET https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs/ 

Veja a seção 'status' do objeto de retorno para obter detalhes relevantes

Próximas etapas

• O que é a Sincronização de Nuvem do Microsoft Entra?
• Transformações
• API de sincronização