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
    • Habilitación de las marcas de inquilino
  • Creación de 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
  • Reescritura híbrida de Exchange
  • Eliminaciones accidentales
    • Habilitación y establecimiento 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 las 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 valor de displayName es la dirección URL del dominio de AD, si se usa en el portal (por ejemplo, contoso.com), pero puede tener un nombre diferente.

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

Creación del trabajo de sincronización

La salida del comando anterior devolverá el valor de 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, podrá encontrar la entidad de servicio mediante la ejecución de la siguiente llamada de 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 quiere 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 matriz de valores inferior, en función de lo que esté intentando hacer:

• Habilite las marcas de inquilino tanto de PHS como de sincronización {clave: "AppKey", valor: "{"appKeyScenario":"AD2AADPasswordHash"}" }

• Habilite solo la marca de inquilino de sincronización (no la active en PHS) { key: "AppKey", value: "{"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.

   • Provision Active Directory users
   • Provision Active Directory inetOrgPersons

   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 objeto 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 al agregar esta asignación de atributos si el nombre ya existiera en la matriz (por ejemplo, si ya hubiera un elemento en attributeMappings que tenga targetAttributeName CredentialData): podría obtener errores de conflicto, o bien las asignaciones preexistentes y las nuevas se podrían combinar, lo que normalmente no es el resultado deseado. El back-end no elimina los duplicados por usted.

   Recuerde realizar esta acción tanto para Usuarios como para 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 escritura diferida 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 la instancia de Active Directory local se amplió 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 escritura diferida 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 o deshabilitar y usar mediante programación eliminaciones accidentales.

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 matriz de valores inferior, en función de lo que esté intentando 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 que tendrá que agregar todos los valores en el cuerpo de la solicitud PUT (como en el ejemplo) para conservar 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 una vez que el trabajo se ponga en cuarentena, deberá 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 identificador de objeto de la entidad de servicio creada en el primer paso y los identificadores de trabajo devuelto por la solicitud que creó 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"
  }
}

Revisión del estado

Para recuperar los estados del trabajo, use el siguiente comando:

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