Configuración mediante programación de la sincronización en la nube mediante MS Graph API

En el documento siguiente se describe cómo replicar un perfil de sincronización desde cero usando solo instancias de MS Graph API.
La estructura de cómo replicar un perfil de sincronización consta de los pasos siguientes. Son las siguientes:

• Configuración mediante programación de la sincronización en la nube mediante MS Graph API
  • Configuración básica
    • Habilitar marcas de inquilino
  • Crear entidades de servicio
  • Creación del trabajo de sincronización
  • Actualización del dominio de destino
  • Habilitación de la sincronización de hashes de contraseñas en la hoja de configuración
  • Escritura diferida híbrida de Exchange
  • Eliminaciones accidentales
    • Activación y ajuste del umbral
    • Permitir eliminaciones
  • Inicio del trabajo de sincronización
  • Revisión del estado
  • Pasos siguientes

Utilice estos comandos del PowerShell de Microsoft Graph para habilitar la sincronización de un inquilino de producción, un requisito previo para poder llamar al servicio web de administración para ese inquilino.

Configuración básica

Habilitación de marcas de inquilino

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

Este cmdlet habilita la sincronización de un inquilino. Usa Get-MgOrganization para obtener el identificador de la organización.

Creación de entidades de servicio

A continuación, es necesario crear la Aplicación o la entidad de servicio de AD2AAD

Debe usar el identificador de aplicación 1a4721b3-e57f-4451-ae87-ef078703ec94. El displayName es la dirección URL del dominio de AD, si se usa en el portal (por ejemplo, contoso.com), pero puede denominarse algo más.

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

Crear trabajo de sincronización

La salida del comando anterior devuelve el objectId de la entidad de servicio que se creó. En este ejemplo, el objectId es aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb. Use Microsoft Graph para agregar un trabajo de sincronización a esa entidad de servicio.

Puede encontrar documentación sobre la creación de un trabajo de sincronización aquí.

Si no registró el identificador, puede encontrar la entidad de servicio ejecutando la siguiente llamada a MS Graph. Para hacer esa llamada, se necesitan los permisos Directory.Read.All:

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

A continuación, busque el nombre de la aplicación en la salida.

Ejecute los dos comandos siguientes para crear dos trabajos: uno para el aprovisionamiento de usuarios o grupos y otro para la sincronización del hash de contraseñas. La solicitud es la misma dos veces, pero con distintos identificadores de plantilla.

Llame a las dos solicitudes siguientes:

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"
}

Serán necesarias dos llamadas si quieres crear ambas.

Valor devuelto de ejemplo (para el aprovisionamiento):

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": []
    }
}

Actualización del dominio de destino

En este inquilino, el identificador de objeto y el identificador de aplicación de la entidad de servicio son los siguientes:

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

Vamos a tener que actualizar el dominio de destino de esta configuración, por lo que habrá que actualizar los secretos de este dominio.

Asegúrese de que el nombre de dominio que usa sea la misma dirección URL que estableció para el controlador de dominio local.

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

Agregue el siguiente par clave-valor en la siguiente matriz de valores en función de lo que intenta hacer:

• Habilite las marcas PHS y sincronizar inquilino { key: "AppKey", value: "{"appKeyScenario":"AD2AADPasswordHash"}" }

• Habilite solo la marca de sincronización de inquilinos (no la active en PHS) { clave: "AppKey", valor: "{"appKeyScenario":"AD2AADProvisioning"}" }

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

La respuesta esperada es: HTTP 204/Sin contenido.

Aquí, el valor de “Dominio” resaltado es el nombre del dominio local Active Directory desde el que se van a aprovisionar las entradas para Microsoft Entra ID.

Habilitación de la sincronización de hashes de contraseñas en la hoja de configuración

En esta sección se trata la habilitación de la sincronización de hashes de contraseñas para una configuración determinada. Esta situación es diferente del secreto de AppKey que habilita la marca de características a nivel de inquilino. Este procedimiento solo es para un único dominio o configuración. Hay que establecer la clave de aplicación en PHS para que este procedimiento funcione de un extremo a otro.

1. Tome el esquema (tenga presente que es bastante grande):

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

2. Tome esta asignación de atributos de CredentialData:

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

3. Busque las siguientes asignaciones de objeto con los siguientes nombres en el esquema

   • Provisionar usuarios de Active Directory
   • Aprovisionamiento de inetOrgPersons de Active Directory

   Las asignaciones de objetos están dentro de schema.synchronizationRules[0].objectMappings (por ahora puede suponer que solo hay una regla de sincronización)

4. Tome la asignación de CredentialData del paso (2) e insértela en las asignaciones de objetos en el paso (3)

   La asignación de objetos tiene una apariencia similar a la siguiente:

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

   Copie la asignación del paso Creación de trabajos AD2AADProvisioning y AD2AADPasswordHash y péguela en la matriz attributeMappings.

   No importa el orden de los elementos de esta matriz (el back-end se ordena para usted). Tenga cuidado de agregar esta asignación de atributos si el nombre ya existe en la matriz. Por ejemplo, si ya hay un elemento en attributeMappings que tiene targetAttributeName CredentialData, puede obtener errores de conflicto o las asignaciones nuevas y preexistentes se pueden combinar. Normalmente, esto no es el resultado deseado. El back-end no elimina réplicas de forma automática.

   Recuerde realizar esta acción para usuarios e inetOrgpersons.

5. Guarde el esquema que cree:

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

Agregue el esquema al cuerpo de la solicitud.

Escritura diferida híbrida de Exchange (versión preliminar pública)

En esta sección se explica cómo activar/desactivar y utilizar la Escritura diferida híbrida de Exchange mediante programación.

La habilitación de la escritura diferida híbrida de Exchange mediante programación requiere dos pasos.

1. Comprobación del esquema
2. Creación del trabajo de reescritura híbrida de Exchange

Comprobación del esquema

Antes de habilitar y usar la escritura diferida híbrida de Exchange, la sincronización en la nube debe determinar si se ha ampliado Active Directory local para incluir el esquema de Exchange.

Puede usar directoryDefinition:discover para iniciar la detección de esquemas.

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

La respuesta esperada es: HTTP 200/OK

La respuesta debería ser similar a la siguiente salida:

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

Ahora compruebe si el atributo mailNickName está presente. Si es así, el esquema se comprueba y contiene los atributos de Exchange. Si no es así, revise los requisitos previos para la escritura diferida híbrida de Exchange.

Creación del trabajo de reescritura híbrida de Exchange

Una vez que haya comprobado el esquema, puede crear el trabajo.

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

Eliminaciones accidentales

En esta sección se explica cómo habilitar, deshabilitar y usar eliminaciones accidentales mediante programación.

Habilitación y establecimiento del umbral

Hay dos valores por trabajo que puede usar, estos son:

• DeleteThresholdEnabled: habilita la prevención de eliminación accidental del trabajo cuando se establece en "true". Está establecido en "true" de manera predeterminada.
• DeleteThresholdValue: define el número máximo de eliminaciones que se permitirán en cada ejecución del trabajo cuando la prevención de eliminaciones accidentales esté habilitada. De manera predeterminada, el valor se establece en 500. Por lo tanto, si el valor estuviera establecido en 500, el número máximo de eliminaciones permitidas será de 499 en cada ejecución.

Los valores de umbral de eliminación forman parte del SyncNotificationSettings y se pueden modificar mediante Graph.

Vamos a tener que actualizar el valor de SyncNotificationSettings que esta configuración tiene como destino, por lo que habrá que actualizar los secretos.

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

Agregue el siguiente par clave-valor en la siguiente matriz de valores en función de lo que intenta hacer:

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

El valor "Habilitado" del ejemplo es para habilitar o deshabilitar los correos electrónicos de notificación cuando el trabajo se pone en cuarentena.

Actualmente, no se admiten solicitudes PATCH para secretos. Por lo tanto, debe agregar todos los valores en el cuerpo de la solicitud PUT, tal como se muestra en el ejemplo, para mantener intactos los demás valores.

Los valores existentes para todos los secretos se pueden recuperar mediante el siguiente comando:

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

Permitir eliminaciones

Para permitir que estas eliminaciones fluyan después de que el trabajo entre en cuarentena, debe emitir un reinicio con solo "ForceDeletes" como ámbito.

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

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

Inicio del trabajo de sincronización

Los trabajos se pueden volver a recuperar con el siguiente comando:

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

Puede encontrar documentación sobre cómo recuperar trabajos aquí.

Para iniciar los trabajos, emita esta solicitud con el id. de objeto de la entidad de servicio creada en el primer paso y los identificadores de trabajo devueltos por la solicitud que ha creado el trabajo.

Puede encontrar documentación sobre cómo iniciar un trabajo aquí.

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

La respuesta esperada es: HTTP 204/Sin contenido.

Otros comandos para controlar el trabajo se documentan aquí.

Para reiniciar un trabajo, use lo siguiente:

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

Estado de revisión

Recupera tus estados de trabajo mediante:

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

Busque los detalles pertinentes en la sección "estado" del objeto devuelto.

Pasos siguientes

• ¿Qué es la sincronización en la nube de Microsoft Entra?
• Transformaciones
• API de sincronización