Compartir a través de

Preguntas más frecuentes sobre el aprovisionamiento de entrada controlado por API

En este artículo se responden las preguntas frecuentes (FAQ) sobre el aprovisionamiento de entrada dirigido por API.

¿Cómo es la nueva API de aprovisionamiento de entrada /bulkUpload diferente de MS Graph Users API?

Hay diferencias significativas entre el aprovisionamiento /bulkUpload por API y el punto de conexión de la API de usuarios de MS Graph.

  • Formato de carga: el punto de conexión de la API de usuarios de MS Graph espera datos en formato OData. El formato de carga de solicitud para la nueva API /bulkUpload de aprovisionamiento de entrada usa construcciones de esquema SCIM. Al invocar esta API, establezca el encabezado "Content-Type" en application/scim+json.
  • Resultado final de la operación:
    • Cuando los datos de identidad se envían al punto de conexión de MS Graph Users API, se procesan inmediatamente y se realiza una operación de creación, actualización y eliminación en el perfil de usuario de Microsoft Entra.
    • El servicio de aprovisionamiento de Microsoft Entra procesa los datos de solicitud enviados a la API de aprovisionamiento /bulkUpload de forma asincrónica. El trabajo de aprovisionamiento aplica reglas de alcance, asignación de atributos y transformación configuradas por el administrador de tecnologías de la información. Esto inicia una Create/Update/Delete operación en el perfil de usuario de Microsoft Entra o en el perfil de usuario de AD local.
  • El administrador de TI conserva el control: con el aprovisionamiento de entrada controlado por API, el administrador de TI tiene más control sobre cómo se procesan y asignan los datos de identidad entrantes a los atributos de Microsoft Entra. Pueden definir reglas de ámbito para excluir determinados tipos de datos de identidad (por ejemplo, datos de contratista) y usar funciones de transformación para derivar nuevos valores antes de establecer los valores de atributo en el perfil de usuario.

¿La API de aprovisionamiento de entrada /bulkUpload es un punto de conexión SCIM estándar?

La API /bulkUpload de aprovisionamiento de entrada de MS Graph usa el esquema SCIM en la carga de la solicitud, pero no es un punto de conexión de API de SCIM estándar. Este es el motivo.

Normalmente, un punto de conexión de servicio SCIM procesa las solicitudes HTTP (POST, PUT, GET) con la carga de SCIM y las traduce a las operaciones respectivas (Crear, Actualizar, Buscar) en el almacén de identidades. El punto de conexión de servicio SCIM coloca la responsabilidad de especificar la semántica de la operación, ya sea crear, actualizar o eliminar una identidad, en el cliente de la API SCIM. Este mecanismo funciona bien en escenarios en los que el cliente de API sabe qué operación desea realizar para los usuarios del almacén de identidades.

El aprovisionamiento de entrada /bulkUpload de MS Graph está diseñado para controlar un escenario de integración de identidad de empresa diferente con tres requisitos únicos:

  1. Capacidad de procesar registros de forma asincrónica en masa (por ejemplo, procesar más de 50 000 registros)
  2. Capacidad de incluir cualquier atributo de identidad en la carga (por ejemplo, costCenter, nivel de pago, badgeId)
  3. Soportar clientes de API que desconocen la semántica de las operaciones. Estos son clientes de API que no son de SCIM y que solo tienen acceso a datos de origen sin procesar (por ejemplo, registros en archivos CSV, tablas SQL o registros de RR. HH.). Estos clientes no tienen la capacidad de procesamiento para leer cada registro y determinar la semántica de operación de Create/Update/Delete en el almacén de identidades.

El objetivo principal del aprovisionamiento entrante de MS Graph /bulkUpload API es permitir que los clientes envíen datos de identidad (por ejemplo, costCenter, nivel de pago, badgeId) desde cualquier origen de datos de identidad (por ejemplo, CSV/SQL/HR) para el procesamiento eventual por parte del servicio de aprovisionamiento de Microsoft Entra. El servicio de aprovisionamiento de Microsoft Entra consume los datos de carga masiva recibidos en este punto de conexión, aplica reglas de asignación de atributos configuradas por el administrador de TI y determina si la carga de datos conduce a la operación (Crear, Actualizar, Habilitar, Deshabilitar) en el almacén de identidades de destino (Microsoft Entra ID / AD local).

¿La API de aprovisionamiento /bulkUpload admite dominios locales de Active Directory como destino?

Sí, la API de aprovisionamiento admite dominios de AD locales como destino.

¿Cómo se obtiene el punto de conexión de la API /bulkUpload para nuestra aplicación de aprovisionamiento?

La API /bulkUpload solo está disponible para las aplicaciones del tipo: "Aprovisionamiento de entrada controlado por API a Microsoft Entra ID" y "Aprovisionamiento de entrada controlado por API en Active Directory local". Puede recuperar el punto de conexión de API único para cada aplicación de aprovisionamiento desde la página principal de la hoja Aprovisionamiento. En Estadísticas hasta la fecha>Ver la información técnica. Copie la URL del endpoint de aprovisionamiento de API.

Tiene el formato :

https://graph.microsoft.com/beta/servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/bulkUpload

¿Cómo se realiza una sincronización completa con la API de aprovisionamiento /bulkUpload?

Para realizar una sincronización completa, use el cliente de API para enviar los datos de todos los usuarios desde el origen de confianza al punto de conexión de API como solicitud masiva. Una vez que envíe todos los datos al punto de conexión de API, el siguiente ciclo de sincronización procesa todos los registros de usuario y le permite realizar un seguimiento del progreso mediante el punto de conexión de la API de registros de aprovisionamiento.

¿Cómo se realiza la sincronización diferencial mediante la API de aprovisionamiento /bulkUpload?

Para realizar una sincronización diferencial, utilice su cliente de API para enviar solo la información sobre los usuarios cuyos datos han cambiado desde la fuente confiable. Una vez que envíe todos los datos al punto de conexión de API, el siguiente ciclo de sincronización procesa todos los registros de usuario y le permite realizar un seguimiento del progreso mediante el punto de conexión de la API de registros de aprovisionamiento.

¿Cómo funciona el reinicio de aprovisionamiento?

Use la opción Reiniciar aprovisionamiento solo si es necesario. Así es como funciona:

Escenario 1: Cuando hace clic en el botón Reiniciar aprovisionamiento y el trabajo se está ejecutando actualmente, el trabajo continúa procesando los datos existentes que ya están almacenados provisionalmente. La operaciónreiniciar el aprovisionamiento no interrumpe un ciclo existente. En el ciclo posterior, el servicio de aprovisionamiento borra las custodias y elige la nueva solicitud masiva para su procesamiento.

Escenario 2: Cuando hace clic en el botón Reiniciar aprovisionamiento y el trabajo no se está ejecutando, antes de ejecutar el ciclo posterior, el motor de aprovisionamiento purga los datos cargados antes del reinicio, borra los elementos en custodia y procesa solamente los nuevos datos entrantes.

¿Cómo podemos crear usuarios utilizando el punto final de la API de aprovisionamiento /bulkUpload?

Este es el modo en que el trabajo de aprovisionamiento asociado al punto de conexión de la API /bulkUpload procesa las cargas de usuario entrantes:

  1. El trabajo recupera la asignación de atributos para el trabajo de aprovisionamiento y registra el par de atributos coincidente (de manera predeterminada, el atributo de API externalId se usa para coincidir con employeeId en Microsoft Entra ID ).
  2. Puede cambiar esta pareja de coincidencia de atributos predeterminada.
  3. El trabajo extrae cada operación presente en la carga de la solicitud masiva.
  4. El trabajo comprueba el identificador de valor coincidente en la solicitud (de forma predeterminada, el atributo externalId) y lo usa para comprobar si hay un usuario en Microsoft Entra ID con el valor coincidente employeeId.
  5. Si el trabajo no encuentra un usuario coincidente, el trabajo aplica las reglas de sincronización y crea un nuevo usuario en el directorio de destino.

Para asegurarse de que los usuarios adecuados se creen en Microsoft Entra ID, defina el par de atributos coincidente correcto en la asignación que identifica de forma única a los usuarios del origen y a Microsoft Entra ID.

¿Cómo generamos valores únicos para UPN?

El servicio de aprovisionamiento no proporciona la capacidad de comprobar si hay userPrincipalName duplicados (UPN) y controlar conflictos. Si la regla de sincronización predeterminada para el atributo UPN genera un valor UPN existente, se produce un error en la operación de creación del usuario.

Estas son algunas opciones que puede considerar para generar UPN únicos:

  1. Agregue la lógica para la generación única de UPN en el cliente de API.
  2. Actualice la regla de sincronización del atributo UPN para usar la función RandomString y establezca el parámetro apply mapping en On object creation only. Ejemplo:

Join("", Replace([userName], , "(?<Suffix>@(.)*)", "Suffix", "", , ), RandomString(3, 3, 0, 0, 0, ), "@", DefaultDomain())

  1. Si va a aprovisionar a Active Directory local, puede usar la función SelectUniqueValue y establecer el parámetro de aplicación de asignación en On object creation only.

¿Cómo enviamos más atributos de Recursos Humanos al endpoint de la API de aprovisionamiento /bulkUpload?

De forma predeterminada, el punto de conexión de API admite el procesamiento de cualquier atributo que forme parte del esquema de usuario principal de SCIM y usuario empresarial. Si desea enviar más atributos, puede ampliar el esquema de la aplicación de aprovisionamiento, asignar los nuevos atributos a los atributos de Microsoft Entra y actualizar la solicitud masiva para enviar esos atributos. Consulte el tutorial Extensión del aprovisionamiento controlado por API para sincronizar atributos personalizados.

¿Cómo se excluyen determinados usuarios del flujo de aprovisionamiento?

Es posible que tenga un escenario en el que quiera enviar todos los usuarios al punto de conexión de API, pero solo incluya determinados usuarios en el flujo de aprovisionamiento y excluya el resto.

El Filtro de ámbito es la herramienta apropiada para ello. En la configuración de la aplicación de aprovisionamiento, puede definir un ámbito de objeto de origen y excluir a determinados usuarios del procesamiento mediante una "regla de inclusión" (por ejemplo, solo procesar usuarios donde departamento EQUALS Sales) o una "regla de exclusión" (por ejemplo, excluir usuarios que pertenecen a Ventas, departamento NOT EQUALS Sales).

Vea Asignación de ámbito a los usuarios o grupos que se van a aprovisionar con filtros de ámbito.

¿Cómo se actualizan los usuarios mediante el punto de conexión de la API /bulkUpload de aprovisionamiento?

Este es el modo en que el trabajo de aprovisionamiento asociado al punto de conexión de la API /bulkUpload procesa las cargas de usuario entrantes:

  1. El trabajo de aprovisionamiento recupera la asignación de atributos para el trabajo de aprovisionamiento y registra el par de atributos coincidente (de forma predeterminada externalId, el atributo de API se usa para coincidir con employeeId en Microsoft Entra ID ). Puede cambiar esta pareja de coincidencia de atributos predeterminada.
  2. El trabajo extrae las operaciones de la carga de la solicitud masiva.
  3. El trabajo comprueba el identificador de coincidencia de valores en la solicitud SCIM (atributo de API externalId por defecto) y lo usa para verificar si hay un usuario en Microsoft Entra ID con el valor employeeId coincidente.
  4. Si el trabajo encuentra un usuario coincidente, aplica las reglas de sincronización y compara los perfiles de origen y destino.
  5. Si el trabajo determina que algunos valores han cambiado, actualiza el registro de usuario correspondiente en el directorio.

Para que los usuarios adecuados se actualicen en Microsoft Entra ID, asegúrese de definir el par de atributos coincidente correcto en la asignación que identifica de forma única a los usuarios del origen y Microsoft Entra ID.

¿Podemos crear más de una aplicación que admita el aprovisionamiento de entrada controlado por API?

Sí, puede hacerlo. Estos son algunos escenarios que pueden requerir más de una aplicación de aprovisionamiento:

Escenario 1: Supongamos que tiene tres orígenes de datos de confianza: uno para empleados, uno para contratistas y otro para proveedores. Puede crear tres aplicaciones de aprovisionamiento independientes: una para cada tipo de identidad con su propia asignación de atributos distintos. Cada aplicación de aprovisionamiento tiene un punto de conexión de API único y puede enviar las cargas respectivas a cada punto de conexión.

Puede recuperar el punto de conexión de API único para cada trabajo desde la página principal de la hoja Aprovisionamiento. Vaya a Estadísticas hasta la fecha>Ver información técnica y, a continuación, copie la URL del Punto de conexión de la API de aprovisionamiento.

Escenario 2: Supongamos que tiene varias fuentes de verdad, cada una con su propio conjunto de atributos. Por ejemplo, HR proporciona atributos de información de trabajo (por ejemplo, jobTitle, employeeType), y el sistema de distintivos proporciona atributos de información de distintivos (por ejemplo badgeId, representados mediante un atributo de extensión). En este escenario, puede configurar dos aplicaciones de aprovisionamiento:

  • Aprovisionamiento de la aplicación n.º 1 que recibe atributos del origen de RR. HH. y crea el usuario.

  • Aprovisionamiento de la aplicación n.º 2 que recibe atributos del sistema de concesión de insignias digitales y solo actualiza los atributos de usuario. La asignación de atributos de esta aplicación está restringida a los atributos de información de Badge y, en Acciones de objeto de destino, solo se habilita la actualización.

  • Ambas aplicaciones usan el mismo par de identificadores coincidente (externalId<->employeeId)

¿Cómo procesamos las terminaciones mediante el endpoint de la API /bulkUpload?

Para procesar las finalizaciones, identifique un atributo en el origen que se usará para establecer la marca accountEnabled en Microsoft Entra ID. Si va a aprovisionar a un Active Directory local, asigne ese atributo de origen al atributo accountDisabled.

De forma predeterminada, el valor asociado al atributo active de esquema sciM Core User determina el estado de la cuenta del usuario en el directorio de destino.

Si el atributo se establece en true, la regla de asignación predeterminada habilita la cuenta. Si el atributo se establece en false, la regla de asignación predeterminada deshabilita la cuenta.

¿Cómo podemos evitar la deshabilitación o eliminación accidental de los usuarios?

Para prevenir y recuperarse de eliminaciones accidentales, se recomienda configurar el umbral de eliminación accidental en la aplicación de aprovisionamiento y habilitar el Reciclador del Active Directory local. En la hoja Asignación de atributos de la aplicación de aprovisionamiento, en Acciones de objeto de destino, deshabilite la operación de eliminación.

Recuperación de cuentas eliminadas

  • Si el directorio de destino de la operación es Microsoft Entra ID, el usuario coincidente se elimina temporalmente. El usuario se puede ver en la página Usuarios eliminados del Centro de administración de Microsoft Entra durante los próximos 30 días y se puede restaurar durante ese tiempo.
  • Si el directorio de destino de la operación es Active Directory local, el usuario coincidente se elimina de forma permanente. Si la Active Directory Recycle Bin está habilitada, puede restaurar el objeto de usuario de AD local eliminado.

¿Necesitamos enviar todos los usuarios desde el sistema de RR. HH. en cada solicitud?

No, no es necesario enviar a todos los usuarios del sistema de RR. HH. / "fuente confiable" en cada solicitud. Solo necesitas enviar los usuarios que deseas crear o actualizar.

¿La API admite todas las acciones HTTP (GET/POST/PUT/PATCH)?

No, el punto de conexión de api de aprovisionamiento /bulkUpload solo admite la acción HTTP POST.

Si quiero actualizar un usuario, ¿necesito enviar una solicitud PUT/PATCH?

No, el punto de conexión de API no admite la solicitud PUT/PATCH. Para actualizar un usuario, envíe los datos asociados al usuario en la carga de solicitud masiva POST.

El trabajo de aprovisionamiento que procesa los datos recibidos por el punto final de la API detecta automáticamente si el usuario recibido en la carga de la solicitud POST debe crearse, actualizarse, habilitarse o deshabilitarse en función de las reglas de sincronización configuradas. Como cliente de API, no es necesario realizar más pasos si quiere que se actualice un perfil de usuario.

¿Cómo se admite la escritura diferida?

La API actual solo admite datos entrantes. Estas son algunas opciones a tener en cuenta para implementar la escritura diferida de atributos (como correo electrónico, nombre de usuario y n. º de teléfono) generados por Microsoft Entra ID, que puede devolver al sistema de RR. HH:

  • Opción 1: conectividad de SCIM con el servicio de punto de conexión o proxy de RR. HH. que, a su vez, actualiza el origen de RR. HH.

    • Si el sistema de registro proporciona un punto de conexión SCIM para las actualizaciones de usuario, puede crear una aplicación SCIM personalizada en la galería de aplicaciones empresariales y configurar el aprovisionamiento como se documenta.
    • Si el sistema de registro no proporciona un punto de conexión SCIM, explore la posibilidad de configurar un servicio SCIM de proxy, que recibe la actualización y propaga el cambio al sistema de RR. HH.

  • Opción 2: Uso del conector ECMA de Microsoft Entra para el escenario de reescritura

    • En función del requisito del cliente, explore si se podría usar uno de los conectores ECMA (PowerShell/ SQL/Web Services).

  • Opción 3: usar la tarea de extensión personalizada de flujos de trabajo de ciclo de vida en un flujo de trabajo de unión

Pasos siguientes

  • Last updated on