Aprovisionamiento de usuarios y grupos con SCIM mediante la API de REST

Acerca del aprovisionamiento de SCIM en GitHub Enterprise Server

Para aprovisionar y mantener cuentas de usuario mediante SCIM, el sistema de administración de identidades debe ofrecer la siguiente funcionalidad:

Autenticación de inicio de sesión único mediante el Lenguaje de Marcado para Aserciones de Seguridad (SAML) 2.0.
Administración del ciclo de vida de los usuarios con System for Cross-domain Identity Management (SCIM)

Al configurar la autenticación y el aprovisionamiento para tu empresa, puedes usar un IdP de asociado u otra combinación de sistemas de administración de identidades.

        [Uso de un proveedor de identidades de asociado](#using-a-partner-identity-provider)

        [Uso de otros sistemas de administración de identidades](#using-other-identity-management-systems)

Uso de un proveedor de identidad asociado

Cada IdP de asociado proporciona una aplicación de "ruta de acceso asfaltada", que implementa el SSO y la administración del ciclo de vida de los usuarios. Para simplificar la configuración, GitHub recomienda usar una aplicación del IdP asociado único para la autenticación y el aprovisionamiento. Para obtener más información y una lista de IdP asociados, consulta Acerca del aprovisionamiento de usuarios con SCIM en GitHub Enterprise Server.

Para obtener más información sobre cómo configurar el aprovisionamiento de SCIM mediante un IdP de asociado, consulta Configuración del aprovisionamiento de SCIM para administrar usuarios.

Uso de otros sistemas de administración de identidades

Si no puedes usar un único IdP asociado para la autenticación y el aprovisionamiento debido a la sobrecarga de migración, los costes de licencia o la inercia organizativa, puedes usar otro sistema de administración de identidades o combinación de sistemas. Los sistemas deben proporcionar autenticación mediante SAML y la administración del ciclo de vida de los usuarios mediante SCIM y deben cumplir las directrices de integración de GitHub.

GitHub no admite expresamente la combinación de IdP asociados para la autenticación y el aprovisionamiento y no prueba todos los sistemas de administración de identidades. Es posible que el equipo de asistencia de GitHub no pueda ayudarle con problemas relacionados con sistemas mixtos o no probados. Si necesita ayuda, debe consultar la documentación del sistema, el equipo de soporte técnico u otros recursos.

Importante

La combinación de Otka y Entra ID para SSO y SCIM (en cualquier orden) no se admite explícitamente. La API de SCIM de GitHub devolverá un error al proveedor de identidades en los intentos de aprovisionamiento si esta combinación está configurada.

Requisitos previos

Para implementar SCIM mediante la API REST, se aplican los requisitos previos generales para usar SCIM en GitHub Enterprise Server. Consulta la sección "Requisitos previos" en Configuración del aprovisionamiento de SCIM para administrar usuarios.

Además, se aplican los siguientes requisitos previos:

Debes haber completado los pasos 1 a 3 en Configuración del aprovisionamiento de SCIM para administrar usuarios.
- Debe usar el personal access token (classic) creado para el usuario de configuración integrado para autenticar las solicitudes a la API REST.
Para aprovisionar usuarios y grupos con la API de REST de GitHub, el sistema de administración de identidades debe admitir el estándar SCIM 2.0. Para más información, vea los siguientes RFC en el sitio web de IETF.
Los registros de usuario de los sistemas que se usan para la autenticación y el aprovisionamiento deben compartir un identificador único y satisfacer los criterios de coincidencia de GitHub. Para más información, consulta Puntos de conexión de API de REST para SCIM en la documentación de la API REST.

Procedimientos recomendados para el aprovisionamiento de SCIM con la API REST de GitHub

Al configurar el sistema de administración de identidades para aprovisionar usuarios o grupos de usuarios en GitHub, GitHub recomienda encarecidamente que cumplas las siguientes directrices.

        [Asegúrate de que el sistema de administración de identidades es el único origen de las operaciones de escritura](#ensure-your-identity-management-system-is-the-only-source-of-write-operations)

        [Envía solicitudes válidas a los puntos de conexión de la API de REST](#send-valid-requests-to-rest-api-endpoints)

        [Aprovisiona usuarios antes de aprovisionar grupos](#provision-users-before-you-provision-groups)

        [Valide el acceso de grupos en GitHub](#validate-access-for-groups-on-github)

        [Reconozca los límites de frecuencia en GitHub](#understand-rate-limits-on-github)

        [Configuración del streaming de registros de auditoría](#configure-audit-log-streaming)

        [Limitación del ámbito del token de SCIM](#limit-the-scope-of-the-scim-token)

        [Comprender los efectos del desaprovisionamiento](#understand-the-effects-of-deprovisioning)

Asegúrate de que el sistema de administración de identidades es el único origen de las operaciones de escritura

Para asegurarte de que el entorno tiene una fuente única de la verdad, solo debes escribir mediante programación en la API de REST para el aprovisionamiento de SCIM desde el sistema de administración de identidades. GitHub recomienda encarecidamente que solo un sistema envíe solicitudes de POST, PUT, PATCH o DELETE a la API.

Sin embargo, puedes recuperar información de forma segura de las API de GitHub con solicitudes GET en scripts o ad hoc por parte de un propietario de la empresa.

Advertencia

Si usas un proveedor de identidades asociado para el aprovisionamiento de SCIM, la aplicación del proveedor de identidades debe ser el único sistema que realice solicitudes de escritura a la API. Si realizas solicitudes ad hoc mediante los métodos POST, PUT, PATCH o DELETE, se producirá un error en los intentos de sincronización posteriores y el aprovisionamiento no funcionará correctamente para tu empresa.

Envía solicitudes válidas a los puntos de conexión de la API de REST

Los puntos de conexión de la API REST de GitHub para aprovisionar usuarios con SCIM requieren solicitudes bien formadas. Ten en cuenta las siguientes directrices:

Las solicitudes que no coinciden con las expectativas de las API devolverán un error 400 Bad Request.
Los puntos de conexión de la API de REST para aprovisionar usuarios con SCIM requieren un encabezado User-Agent. GitHub rechazará las solicitudes sin este encabezado.

Aprovisiona usuarios antes de aprovisionar grupos

Los grupos SCIM son eficaces para la administración del acceso de los usuarios a escala. Por ejemplo, puedes usar grupos en el sistema de administración de identidades para administrar la pertenencia a equipos y organizaciones en GitHub.

Para administrar la pertenencia al equipo con grupos en el sistema de administración de identidades, debes completar secuencialmente los pasos siguientes:

Configura cuentas de usuario en GitHub.
Configura un grupo en GitHub.
Actualiza la pertenencia del grupo en el sistema de administración de identidades.
Crea un equipo en GitHub que esté asignado al grupo en el sistema de administración de identidades.

Valida el acceso para grupos en GitHub.

Si administras el acceso mediante grupos en el sistema de administración de identidades, puedes validar que los usuarios obtengan el acceso que quieres. Puedes usar la API REST para comparar las pertenencias a grupos de tu sistema con la comprensión de GitHub de esos grupos. Para más información, consulta Puntos de conexión de la API de REST para grupos externos y Puntos de conexión de la API de REST para equipos en la documentación de la API de REST.

Reconozca los límites de frecuencia en GitHub

Si un administrador del sitio ha habilitado los límites de tasa en su instancia, puede encontrar errores al aprovisionar usuarios por primera vez. Puedes revisar los registros de IdP para confirmar si se ha producido un error en las operaciones de envío de cambios o de aprovisionamiento de SCIM que se han intentado realizar debido a un error de límite de frecuencia. La respuesta a un intento fallido de aprovisionamiento dependerá del IdP.

Para más información, consulta Límites de tasa de la API REST.

Configura el streaming de registros de auditoría

El registro de auditoría de la empresa muestra detalles sobre tu actividad. Puede usar el registro de auditoría para respaldar la configuración de SCIM. Para más información, consulta Registro de auditoría de una empresa.

Debido al volumen de eventos de este registro, GitHub conserva los datos durante 180 días. Para garantizar que no se pierden datos del registro de auditoría y para ver una actividad más detallada en este, GitHub recomienda configurar el streaming de registros de auditoría. Al transmitir el registro de auditoría, tienes la opción de transmitir eventos de las solicitudes de API, incluidas las solicitudes a los puntos de conexión de API REST para el aprovisionamiento de SCIM. Para más información, consulta Streaming del registro de auditoría de su empresa.

Limitar el ámbito del token de SCIM

Para mejorar la posición de seguridad, se recomienda usar un personal access token (classic) con solamente el ámbito scim:enterprise para limitar el acceso del token a los puntos de conexión de la API de REST necesarios para realizar llamadas SCIM.

Si actualmente usas un token con el ámbito admin:enterprise, ten en cuenta que este token concede acceso a todas las acciones de la empresa. Puedes intercambiar el token por un nuevo token únicamente con el ámbito scim:enterprise sin interrupciones.

Comprender los efectos del desaprovisionamiento

Para quitar el acceso de un usuario de GitHub, puedes enviar una solicitud de desaprovisionamiento temporal o una solicitud de desaprovisionamiento permanente al proveedor de SCIM. El desaprovisionamiento duro es una acción irreversible que suspende permanentemente la cuenta de GitHub de un usuario.

Antes de implementar una integración de API, asegúrate de comprender los tipos de desaprovisionamiento y los efectos que tienen. Para obtener información sobre los diferentes tipos de desaprovisionamiento, sus efectos y los eventos de registro de auditoría que generan, consulta Desaprovisionamiento y restablecimiento de usuarios con SCIM.

Aprovisionamiento de usuarios mediante la API de REST

Para aprovisionar, enumerar o administrar usuarios, haz solicitudes a los siguientes puntos de conexión de la API de REST. Puedes leer sobre los puntos de conexión de API asociados en la documentación de la API de REST y ver ejemplos de código además de revisar los eventos de registro de auditoría asociados a cada solicitud.

Antes de que una persona con una identidad en el sistema de administración de identidades pueda iniciar sesión en su empresa, debe crear el usuario correspondiente. Tu empresa no requiere una licencia disponible para aprovisionar una nueva cuenta de usuario.

Para obtener información general sobre los atributos admitidos para los usuarios, consulta SCIM en la documentación de la API de REST.
Puedes ver los usuarios aprovisionados en la interfaz de usuario de GitHub. Para más información, consulta Visualizar a las personas en tu empresa.
Los administradores empresariales con acceso a la CLI pueden exportar un CSV completo de identidades de usuario aprovisionadas de SCIM mediante la herramienta ghe-scim-identities-csv.

Acción	Método	Punto de conexión y más información	Eventos en el registro de auditoría
Enumera a todos los usuarios aprovisionados para tu empresa, incluidos los usuarios que están desaprovisionados temporalmente configurando `active` en `false`.	`GET`	`/scim/v2/Users`	N/D
Crear un usuario. La respuesta de la API incluye un campo `id` para identificar de forma única al usuario.	`POST`	`/scim/v2/Users`	`external_identity.provision` `user.create` Si la solicitud añade el rol `enterprise_owner`, `business.add_admin` Si la solicitud añade el rol `billing_manager`, `business.add_billing_manager` Si la solicitud tiene éxito, `external_identity.scim_api_success` Si se produce un error en la solicitud, `external_identity.scim_api_failure`
Recupera un usuario existente de tu empresa mediante el campo `id` de la solicitud `POST` que enviaste para crear el usuario.	`GET`	`/scim/v2/Users/{scim_user_id}`	N/D
Actualiza todos los atributos de un usuario existente mediante el campo `id` de la solicitud `POST` que enviaste para crear el usuario. Actualiza `active` a `false` para desaprovisionar temporalmente al usuario o `true` para reactivar el usuario. Para más información, consulta Desaprovisionamiento temporal de usuarios con la API de REST y Reactivación de usuarios con la API de REST.	`PUT`	`/scim/v2/Users/{scim_user_id}`	`external_identity.update`, a menos que se desaprovisione o vuelva a aprovisionar temporalmente Si la solicitud añade el rol `enterprise_owner`, `business.add_admin` Si la solicitud añade `billing_manager`, `business.add_billing_manager` Si la solicitud quita el rol `enterprise_owner`, `business.remove_admin` Si la solicitud quita el rol `billing_manager`, `business.remove_billing_manager` Si la solicitud tiene éxito, `external_identity.scim_api_success` Si se produce un error en la solicitud, `external_identity.scim_api_failure`
Actualiza un atributo individual para un usuario existente mediante el campo `id` de la solicitud `POST` que enviaste para crear el usuario. Actualiza `active` a `false` para desaprovisionar temporalmente al usuario o `true` para reactivar el usuario. Para más información, consulta Desaprovisionamiento temporal de usuarios con la API de REST y Reactivación de usuarios con la API de REST.	`PATCH`	`/scim/v2/Users/{scim_user_id}`	`external_identity.update`, a menos que se desaprovisione o vuelva a aprovisionar temporalmente Si la solicitud añade el rol `enterprise_owner`, `business.add_admin` Si la solicitud añade `billing_manager`, `business.add_billing_manager` Si la solicitud quita el rol `enterprise_owner`, `business.remove_admin` Si la solicitud quita el rol `billing_manager`, `business.remove_billing_manager` Si la solicitud tiene éxito, `external_identity.scim_api_success` Si se produce un error en la solicitud, `external_identity.scim_api_failure`
Para suspender permanentemente a un usuario existente, puede desaprovisionarlo definitivamente. Después de un desaprovisionamiento permanente, no puedes reactivar el usuario y debes aprovisionar el usuario como un nuevo usuario. Para obtener más información, consulte Desaprovisionamiento permanente de usuarios con la API REST.	`DELETE`	`/scim/v2/Users/{scim_user_id}`	`external_identity.deprovision` `user.remove_email` Si la solicitud tiene éxito, `external_identity.scim_api_success` Si se produce un error en la solicitud, `external_identity.scim_api_failure`

Desaprovisionamiento suave de usuarios con la API REST

Para evitar que un usuario inicie sesión para acceder a tu empresa, puedes desaprovisionar temporalmente al usuario mediante el envío de una solicitud PUT o PATCH para actualizar el campo active de un usuario de false a /scim/v2/Users/{scim_user_id}. Al desaprovisionar temporalmente un usuario, GitHub ofusca los campos login y email del registro de usuario y el usuario se suspende.

Reactivación de usuarios con la API de REST

Para permitir que un usuario desaprovisionado temporalmente inicie sesión para acceder a tu empresa, anula la suspensión al usuario mediante el envío de una solicitud PUT o PATCH a /scim/v2/Users/{scim_user_id} para actualizar el campo de un usuario de active a true.

Desaprovisionamiento forzado de usuarios con la API REST

Importante

El desaprovisionamiento duro es una acción irreversible que suspende permanentemente la cuenta de GitHub de un usuario. Consulta Descripción de los efectos del desaprovisionamiento.

Puedes desaprovisionar de forma permanente al usuario mediante el envío de una solicitud DELETE a /scim/v2/Users/{scim_user_id}. Tu empresa conservará los recursos y comentarios creados por el usuario.

Aprovisionamiento de grupos mediante la API de REST

Para controlar el acceso a repositorios de tu empresa, puedes usar grupos de tu sistema de administración de identidades para controlar la organización y la pertenencia al equipo de los usuarios en tu empresa. Puedes leer sobre los puntos de conexión de API asociados en la documentación de la API de REST y ver ejemplos de código además de revisar los eventos de registro de auditoría asociados a cada solicitud.

Aunque su empresa no requiere una licencia disponible para aprovisionar una nueva cuenta de usuario, si aprovisiona un grupo que da como resultado la incorporación de usuarios en una organización, debe tener licencias disponibles para esos usuarios.

Para obtener información general sobre los atributos admitidos para los grupos, consulta SCIM en la documentación de la API de REST.
Para obtener información general sobre los eventos de registro de auditoría relacionados con los grupos, consulta Eventos de registro de auditoría de la empresa.
Puedes ver los grupos aprovisionados en la interfaz de usuario de GitHub. Para más información, consulta Administrar membrecías de equipo con grupos de proveedor de identidad.

Acción	Método	Punto de conexión y más información	Eventos relacionados en el registro de auditoría
Enumera todos los grupos definidos para tu empresa.	`GET`	`/scim/v2/Groups`	N/D
Para definir un nuevo grupo de IdP para tu empresa, crea el grupo. La respuesta de la API incluye un campo `id` para identificar de forma única al grupo.	`POST`	`/scim/v2/Groups`	`external_group.provision` `external_group.update_display_name` Si la solicitud incluía una lista de usuarios, `external_group.add_member` Si la solicitud tiene éxito, `external_group.scim_api_success` Si se produce un error en la solicitud, `external_group.scim_api_failure`
Recupera un grupo existente de tu empresa mediante `id` de la solicitud `POST` que enviaste para crear el grupo.	`GET`	`/scim/v2/Groups/{scim_group_id}`	N/D
Actualiza todos los atributos de un grupo existente.	`PUT`	`/scim/v2/Groups/{scim_group_id}`	`external_group.update` Si la solicitud actualiza el nombre del grupo, `external_group.update_display_name` Si la solicitud agrega un usuario al grupo, `external_group.add_member` Si la solicitud quita un usuario del grupo, `external_group.remove_member` Si la solicitud tiene éxito, `external_group.scim_api_success` Si se produce un error en la solicitud, `external_group.scim_api_failure` Es posible que aparezcan eventos adicionales en el registro de auditoría en función de si el usuario ya es miembro de la organización con el equipo que vinculaste al grupo de IdP. Para obtener más información, consulta Eventos de registro de auditoría adicionales para los cambios en grupos de IdP.
Actualiza un atributo individual para un grupo existente.	`PATCH`	`/scim/v2/Groups/{scim_group_id}`	`external_group.update` Si la solicitud actualiza el nombre del grupo, `external_group.update_display_name` Si la solicitud agrega un usuario al grupo, `external_group.add_member` Si la solicitud quita un usuario del grupo, `external_group.remove_member` Si la solicitud tiene éxito, `external_group.scim_api_success` Si se produce un error en la solicitud, `external_group.scim_api_failure` Es posible que aparezcan eventos adicionales en el registro de auditoría en función de si el usuario ya es miembro de la organización con el equipo que vinculaste al grupo de IdP. Para obtener más información, consulta Eventos de registro de auditoría adicionales para los cambios en grupos de IdP.
Elimina completamente un grupo existente.	`DELETE`	`/scim/v2/Groups/{scim_group_id}`	`external_group.delete` Si la solicitud elimina un grupo vinculado a un equipo de una organización donde el usuario no tiene ninguna otra pertenencia al equipo, `org.remove_member` Si la solicitud elimina un grupo vinculado a un equipo de una organización donde el usuario tiene otra pertenencia al equipo, `team.remove_member` Si la solicitud tiene éxito, `external_group.scim_api_success` Si se produce un error en la solicitud, `external_group.scim_api_failure`

Eventos de registro de auditoría adicionales para cambios en grupos de IdP

Si actualizas los miembros de un grupo existente mediante una solicitud PUT o PATCH a /scim/v2/Groups/{scim_group_id}, GitHub puede agregar el usuario a la organización o quitar el usuario de la organización en función de la pertenencia actual de la organización. Si el usuario ya es miembro de al menos un equipo de la organización, el usuario es miembro de la organización. Si el usuario no es miembro de ningún equipo de la organización, es posible que el usuario tampoco sea miembro de la organización.

Si la solicitud actualiza un grupo vinculado a un equipo de una organización en la que un usuario aún no es miembro, además de external_group.update, los siguientes eventos aparecen en el registro de auditoría:

org.add_member
Si la solicitud agrega un usuario a un grupo vinculado a un equipo de una organización en la que el usuario aún no es miembro, org.add_member
Si la solicitud agrega el usuario a un grupo vinculado a un equipo de una organización, team.add_member

Si la solicitud actualiza un grupo vinculado a un equipo de una organización en la que un usuario ya es miembro, además de external_group.update, los siguientes eventos aparecen en el registro de auditoría:

Si la solicitud elimina al usuario de un grupo vinculado a un equipo de una organización, y el equipo no es el último equipo de la organización donde el usuario es miembro, team.remove_member
Si la solicitud elimina un usuario de un grupo vinculado al último equipo de una organización donde el usuario ya es miembro, org.remove_member

Solución de problemas de aprovisionamiento de SCIM

Si tus solicitudes a la API REST están limitadas por tasa, puedes obtener más información en Comprender los límites de tasa en GitHub.
Todas las solicitudes de SCIM que recibe GitHub, a excepción de las solicitudes GET de HTTP correctas, generarán un evento registro de auditoría. Estos registros contendrán información útil sobre el resultado de la solicitud, la información de carga y los errores. Estos registros se pueden usar para determinar si GitHub ha recibido o no una solicitud de SCIM y para solucionar problemas de errores de API.
- Para determinar si se ha aprovisionado un usuario, puedes usar la siguiente consulta de registro de auditoría: action:external_identity.provision user:USERNAME
- Si no encuentras un usuario con la consulta anterior, puedes buscar eventos action:external_identity.scim_api_failure por la fecha en la que esperabas haber recibido la solicitud.
Si se produce un error en una solicitud de SCIM y no puede determinar la causa, compruebe el estado del sistema de administración de identidades para asegurarse de que los servicios estaban disponibles.
Si se produce un error 400 en una solicitud para aprovisionar un usuario y el mensaje de error del registro del sistema de administración de identidades indica problemas con el formato de nombre de usuario o propiedad de la cuenta, revisa Consideraciones sobre el nombre de usuario para la autenticación externa.
Después de la autenticación correcta, GitHub vincula al usuario que se autenticó en una identidad aprovisionada por SCIM. Los identificadores únicos para la autenticación y el aprovisionamiento deben coincidir. Para obtener más información, consulte Puntos de conexión de API de REST para SCIM..
Si administras el acceso mediante grupos en el sistema de administración de identidades, puedes solucionar problemas mediante la API REST o la interfaz de usuario web para GitHub.
- Puedes utilizar la API REST para comparar las pertenencias a grupos de tu sistema de gestión de identidades con la comprensión que tiene GitHub de esos grupos. Consulta Puntos de conexión de la API de REST para grupos externos y Puntos de conexión de la API de REST para equipos.
- Para más información sobre cómo solucionar problemas mediante la UI web, consulta Resolución de problemas de pertenencia al equipo con grupos de proveedores de identidad.

Para obtener sugerencias de solución de problemas adicionales, consulta Solución de problemas de administración de acceso e identidad para la empresa.

Aprovisionamiento de usuarios y grupos con SCIM mediante la API de REST

En este artículo