Share via

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

  • Artículo

Este artículo contiene las Preguntas más frecuentes (P+F) sobre el aprovisionamiento de entrada controlado por API.

¿Qué diferencias presenta la nueva API /bulkUpload de aprovisionamiento de entrada con respecto a la API de usuarios de MS Graph?

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: punto de conexión de la API de usuarios de MS Graph espera recibir los 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, se establece 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 la API de usuarios de MS Graph, 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.
    • Los datos de solicitud enviados a la API de aprovisionamiento /bulkUpload son procesados de forma asincrónica por el servicio de aprovisionamiento de Microsoft Entra. El trabajo de aprovisionamiento aplica reglas de ámbito, transformación y asignación de atributos configurados por el administrador de TI. Esto inicia una operación Create/Update/Delete 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. Puede 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.

¿Es la API /bulkUpload de aprovisionamiento de entrada 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. Y esto es así por las siguientes razones.

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 asigna al cliente de la API de SCIM la responsabilidad de especificar la semántica de la operación (si se va a crear, actualizar o eliminar una identidad). 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 empresarial diferente formado por 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, pay grade, badgeId)
  3. Admitir clientes de API que no son conscientes de la semántica de la operación. 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 de la API /bulkUpload de aprovisionamiento de entrada de MS Graph 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 ID consume los datos de carga masiva recibidos en este punto de conexión, aplica las 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 o AD local).

¿Admite la API /bulkUpload de aprovisionamiento los dominios de Active Directory local como destino?

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

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

La API /bulkUpload solo está disponible para las aplicaciones "aprovisionamiento entrante controlado por API en Microsoft Entra ID " y "aprovisionamiento entrante controlado por API para 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 información técnica, copie la dirección URL del punto de conexión de API de aprovisionamiento.

Tiene este formato:

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

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

Para realizar una sincronización completa, envíe los datos de todos los usuarios con el cliente de API 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 la API, el siguiente ciclo de sincronización procesará todos los registros de usuario y le permitirá realizar un seguimiento del progreso mediante el punto de conexión de la API de registros de aprovisionamiento.

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

Para realizar una sincronización delta, envíe con el cliente de API información exclusivamente sobre los usuarios cuyos datos han cambiado en el origen de confianza. Una vez que envíe todos los datos al punto de conexión de la API, el siguiente ciclo de sincronización procesará todos los registros de usuario y le permitirá 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. Funcionamiento:

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 las custodias y solo procesa los nuevos datos entrantes.

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

El trabajo de aprovisionamiento asociado al punto de conexión de la API /bulkUpload procesa las cargas de usuario entrantes de la siguiente manera:

  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 este par de coincidencia de atributos predeterminado.
  3. El trabajo extrae cada operación presente en la carga de la solicitud masiva.
  4. El trabajo comprueba el identificador de coincidencia de valores en la solicitud (de forma predeterminada, el atributo externalId) y lo usa para comprobar si hay un usuario en Microsoft Entra ID con un valor coincidente employeeId.
  5. Si el trabajo no encuentra un usuario coincidente, 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 se generan 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 de aplicación de asignación 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 se envían más atributos de RR. HH. al punto de conexión de la API /bulkUpload de aprovisionamiento?

De forma predeterminada, el punto de conexión de la API admite el procesamiento de cualquier atributo que forme parte del esquema de usuario principal de SCIM y usuario empresarial. Si quiere 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?

Puede que necesite enviar a todos los usuarios al punto de conexión de la API, pero solo incluir a algunos de ellos en el flujo de aprovisionamiento y excluir al 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 el departamento sea igual a Ventas con el operador EQUALS) o una "regla de exclusión" (por ejemplo, excluir a los usuarios que pertenecen a Ventas, con el operador NOT EQUALS).

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?

El trabajo de aprovisionamiento asociado al punto de conexión de la API /bulkUpload procesa las cargas de usuario entrantes de la siguiente manera:

  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 este par de coincidencia de atributos predeterminado.
  2. El trabajo extrae las operaciones de la carga de la solicitud masiva.
  3. El trabajo comprueba el identificador de coincidencia de valor en la solicitud SCIM (de manera predeterminada: el atributo de API externalId) y lo usa para comprobar si hay un usuario en Microsoft Entra ID con un 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, otro 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 copie la dirección URL del punto de conexión de API de aprovisionamiento.

Escenario 2: Supongamos que tiene varias fuentes de verdad, cada una con su propio conjunto de atributos. Por ejemplo, RR. HH. proporciona atributos de información del trabajo (por ejemplo, jobTitle, employeeType) y el sistema Badging proporciona sus propios atributos de información (por ejemplo badgeId, que se representa 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 Badging 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 finalizaciones mediante el punto de conexión 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 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 usuarios?

Para evitar y recuperarse de eliminaciones accidentales, se recomienda configurar el umbral de eliminación accidental en la aplicación de aprovisionamiento y habilitar la papelera de reciclaje de 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 puede restaurarse 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 Papelera de reciclaje de Active Directory está habilitada, puede restaurar el objeto de usuario de AD local eliminado.

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

No, no es necesario enviar a todos los usuarios desde el sistema de RR. HH. o "fuente de verdad" en cada solicitud. Solo tiene que enviar a los usuarios que desea crear o actualizar.

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

No, el punto de conexión de la 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 la 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 de conexión de API detecta automáticamente si el usuario recibido en la carga de la solicitud POST debe crearse, actualizarse, habilitar o deshabilitarse en función de las reglas de sincronización configuradas. Como cliente de API, no es necesario realizar más pasos si desea actualizar un perfil de usuario.

¿Cómo se admite la escritura diferida?

La API actual solo admite datos de entrada. 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 en este enlace.
    • Si el sistema de registro no proporciona un punto de conexión SCIM, plantéese configurar un servicio SCIM de proxy que reciba la actualización y propague el cambio al sistema de RR. HH.

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

    • 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