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

O documento a seguir descreve como replicar um perfil de sincronização do zero usando apenas APIs MSGraph.
A estrutura de como replicar um perfil de sincronização consiste nas seguintes etapas. Eles são:

• Como configurar programaticamente a sincronização na nuvem usando a API do MS Graph
  • Configuração básica
    • Ativar sinalizadores de locatário
  • Criar principais de serviço
  • Criar trabalho de sincronização
  • Atualizar domínio de destino
  • Ativar a sincronização dos hashes de palavras-passe no painel de configuração
  • Write-back híbrido do Exchange
  • Exclusões acidentais
    • Habilitando e definindo o limite
    • Permitir exclusões
  • Iniciar trabalho de sincronização
  • Estado da revisão
  • Passos seguintes

Use esses comandos do Microsoft Graph PowerShell para habilitar a sincronização para um locatário de produção, um pré-requisito para poder chamar o Serviço Web de Administração para esse locatário.

Configuração básica

Ativar 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 permite a sincronização para um locatário. Ele usa o Get-MgOrganization para obter a ID da organização.

Criar principais de serviço

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

Você precisa usar este aplicativo ID 1a4721b3-e57f-4451-ae87-ef078703ec94. O displayName é o URL do domínio do AD, se usado 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, o objectId é aaaaa-0000-1111-2222-bbbbbbbbbbbb. Use o Microsoft Graph para adicionar um synchronizationJob a essa entidade de serviço.

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

Se você não gravou a ID, você pode encontrar a entidade de serviço executando a seguinte chamada do MS Graph. Você precisa de permissões Directory.Read.All 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 seguintes para criar dois trabalhos: um para o aprovisionamento de utilizadores/grupos e outro para a sincronização do hash de palavras-passe. É 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 de retorno (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 de objeto e o identificador de 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 que esta configuração está direcionando, então atualize os segredos para este domínio.

Verifique se o nome de domínio usado é o mesmo URL definido 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 na matriz de valores abaixo com base no que você está tentando fazer:

• Ative os sinalizadores de inquilino de sincronização e a PHS { key: "AppKey", value: "{"appKeyScenario":"AD2AADPasswordHash"}" }

• Habilite apenas o sinalizador de locatário de sincronização (não ative 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 "Domínio" realçado é o nome do domínio do Ative Directory local a partir do qual as entradas devem ser provisionadas para o Microsoft Entra ID.

Ativar a sincronização dos hashes de palavras-passe no painel de configuração

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

1. Pegue o esquema (aviso, é muito grande):

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

2. Execute este mapeamento de atributos CredentialData:

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

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

   • Provisionar usuários do Ative Directory
   • Provisionar o Ative Directory inetOrgPersons

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

4. Pegue o mapeamento CredentialData da etapa (2) e insira-o nos mapeamentos de objeto na etapa (3)

   O mapeamento de objetos tem 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 nessa 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 obter erros de conflito ou os mapeamentos pré-existentes e novos podem ser combinados, geralmente não o resultado desejado. Backend não dedupe para você.

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

5. Salve o esquema criado:

   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.

Habilitar o write-back híbrido do Exchange programaticamente requer duas etapas.

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

Verificação do esquema

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

Você pode usar 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 deve ser semelhante à seguinte saída:

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 for, seu esquema é verificado e contém os atributos do Exchange. Caso contrário, revise os pré-requisitos para o write-back híbrido do Exchange.

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

Depois de verificar o esquema, você pode 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 aborda como ativar/desabilitar programaticamente e usar exclusões acidentais programaticamente.

Habilitando e definindo o limite

Há duas configurações por trabalho que você pode usar, são elas:

• DeleteThresholdEnabled - Permite a prevenção de 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 permitido em cada execução do trabalho quando a prevenção de exclusões acidentais está habilitada. O valor é definido como 500 por padrão. Assim, se o valor for definido como 500, o número máximo de exclusões permitidas é 499 em cada execução.

As configurações de limite de exclusão fazem parte do SyncNotificationSettings e podem ser modificadas via gráfico.

Vamos precisar atualizar o SyncNotificationSettings que essa configuração está direcionando, então 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 é para ativar/desabilitar e-mails de notificação quando o trabalho é colocado em quarentena.

Atualmente, não suportamos solicitações PATCH para segredos, então você precisa 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 usando:

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

Permitir exclusões

Para permitir que essas exclusões fluam depois que o trabalho entrar em quarentena, você precisa emitir uma reinicialização com apenas "ForceDeletes" como 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 os identificadores de trabalho retornados da solicitação que criou o trabalho.

A documentação sobre como começar 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"
  }
}

Estado da revisão

Recupere os estados do seu trabalho através de:

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

Procure na seção 'status' do objeto de retorno para obter detalhes relevantes

Próximos passos

• O que é o Microsoft Entra Cloud Sync?
• Transformações
• API de sincronização