Подготовка пользователей и групп с помощью SCIM с помощью REST API

Примечание.

GitHub рекомендует тестировать подготовку в среде, изолированной от рабочих данных в idP и GitHub.

Сведения о IAM для Enterprise Managed Users

Если ваша организация на GitHub создана для Enterprise Managed Users, необходимо настроить внешнюю систему управления удостоверениями для подготовки и обслуживания учетных записей пользователей. Ваша система управления удостоверениями должна предложить следующие функции:

Проверка подлинности единого входа реализует один из следующих двух стандартов единого входа:
- Язык разметки утверждений безопасности (SAML) 2.0
- OpenID Connect (OIDC), который поддерживается только при использовании Microsoft Entra ID (ранее известного как Azure AD)
Управление жизненным циклом пользователей с помощью system for Cross-domain Identity Management (SCIM)

При настройке проверки подлинности и подготовки для вашего предприятия можно использовать поставщика удостоверений или использовать другую комбинацию систем управления удостоверениями.

        [Использование поставщика удостоверений партнера](#using-a-partner-identity-provider)

        [Использование других систем управления удостоверениями](#using-other-identity-management-systems)

Использование поставщика удостоверений партнера

Каждый партнер idP предоставляет приложение "проложенный путь", которое реализует как единый вход, так и управление жизненным циклом пользователей. Чтобы упростить настройку, GitHub рекомендует использовать одно приложение поставщика удостоверений для проверки подлинности и подготовки. Дополнительные сведения и список поставщиков удостоверений партнеров см. в статье Сведения о Enterprise Managed Users.

Дополнительные сведения о настройке подготовки SCIM с помощью поставщика удостоверений партнера см. в разделе Настройка подготовки SCIM for Enterprise Managed Users.

Использование других систем управления удостоверениями

Если вы не можете использовать единый идентификатор партнера для проверки подлинности и подготовки из-за затрат на миграцию, затрат на лицензирование или инерцию организации, можно использовать другую систему управления удостоверениями или комбинацию систем. Системы должны обеспечить проверку подлинности с помощью SAML и управления жизненным циклом пользователей с помощью SCIM, и должны соответствовать рекомендациям по интеграции GitHub.

GitHub не поддерживает сочетание поставщиков удостоверений для проверки подлинности и подготовки партнеров и не проверяет все системы управления удостоверениями. GitHub группе поддержки %}может оказаться не в состоянии помочь вам с проблемами, связанными с смешанными или непроверенными системами. Если вам нужна помощь, необходимо обратиться к документации системы, группе поддержки или другим ресурсам.

Внимание

Сочетание Okta и Entra ID для единого входа и SCIM (в любом порядке) явно не поддерживается. API SCIM %% данных.product.github %}возвращает ошибку поставщику удостоверений при попытке подготовки при настройке этого сочетания.

Необходимые компоненты

При начале использования GitHub Enterprise Cloudнеобходимо создать корпоративный с управляемыми пользователями. Дополнительные сведения см. в разделе Выбор типа предприятия для GitHub Enterprise Cloud.
Перед настройкой подготовки необходимо настроить проверку подлинности для пользователей. Для этой конфигурации требуется настройка как в системе управления удостоверениями, так и в GitHub. Дополнительные сведения см. в разделе Настройка проверки подлинности для корпоративных управляемых пользователей.
Необходимо включить открытую конфигурацию SCIM для вашего предприятия. Дополнительные сведения см. в разделе Настройка подготовки SCIM for Enterprise Managed Users.
Чтобы выполнить проверку подлинности запросов к конечным точкам REST API для SCIM, необходимо использовать personal access token (classic), связанный с пользователем настройки предприятия. Для маркера требуется область scim:enterprise . GitHub рекомендует не настраивать дату окончания срока действия маркера. См . раздел AUTOTITLE.
Чтобы подготовить пользователей и группы с помощью REST API GitHub, ваша система управления удостоверениями должна поддерживать стандарт SCIM 2.0. Дополнительные сведения см. на веб-сайте IETF ниже.
Записи пользователей для систем, используемых для проверки подлинности и подготовки, должны предоставлять уникальный идентификатор и удовлетворять критериям соответствия GitHub. Дополнительные сведения см . в статье AUTOTITLE в документации по REST API.

Рекомендации по подготовке SCIM с помощью REST API GitHub

При настройке системы управления удостоверениями для подготовки пользователей или групп пользователей на GitHubGitHub настоятельно рекомендуется придерживаться следующих рекомендаций.

        [Убедитесь, что ваша система управления удостоверениями является единственным источником операций записи](#ensure-your-identity-management-system-is-the-only-source-of-write-operations)

        [Отправка допустимых запросов в конечные точки REST API](#send-valid-requests-to-rest-api-endpoints)

        [Подготовка пользователей перед подготовкой групп](#provision-users-before-you-provision-groups)

        [Проверка доступа для групп в GitHub](#validate-access-for-groups-on-github)

        [Общие сведения об ограничениях скорости для GitHub](#understand-rate-limits-on-github)

        [Настройка потоковой передачи](#configure-audit-log-streaming) журналов аудита

        [Ограничение области маркера](#limit-the-scope-of-the-scim-token) SCIM

        [Общие сведения о последствиях отмены подготовки](#understand-the-effects-of-deprovisioning)

Убедитесь, что ваша система управления удостоверениями является единственным источником операций записи

Чтобы убедиться, что в вашей среде есть один источник истины, необходимо выполнять только программную запись в REST API для подготовки SCIM из системы управления удостоверениями. GitHub настоятельно рекомендует отправлять только одну систему POST, PUT``PATCHили DELETE запросы к API.

Однако вы можете безопасно получить информацию из API GitHubс GET запросами в скриптах или нерегламентированных запросах владельцем предприятия.

Предупреждение

При использовании поставщика удостоверений партнера для подготовки SCIM приложение для поставщика удостоверений должно быть единственной системой, которая выполняет запросы на запись в API. Если вы выполняете нерегламентированные запросы с помощью POSTметодов , PUT``PATCHили DELETE методов, последующие попытки синхронизации завершаются ошибкой, а подготовка не будет работать должным образом для вашего предприятия.

Отправка допустимых запросов в конечные точки REST API

GitHub конечных точек REST API %}для подготовки пользователей с scIM требуют хорошо сформированных запросов. Помните следующие рекомендации:

Запросы, которые не соответствуют ожиданиям API, возвращают ошибку 400 Bad Request .
Конечные точки REST API для подготовки пользователей с помощью SCIM требуют заголовка User-Agent . GitHub отклоняет запросы без этого заголовка.
Если ваша организация находится на GHE.com, убедитесь, что вы отправляете запросы API в конечную точку для вашей организации api.SUBDOMAIN.ghe.com.

Подготовка пользователей перед подготовкой групп

Группы SCIM эффективны для управления доступом пользователей в большом масштабе. Например, вы можете использовать группы в системе управления удостоверениями для управления членством в команде и организации на GitHub.

Чтобы управлять членством в группе с группами в системе управления удостоверениями, необходимо последовательно выполнить следующие действия.

Подготовка учетных записей пользователей на GitHub.
Подготовьте группу на GitHub.
Обновите членство в группе в системе управления удостоверениями.
Создайте команду на GitHub, сопоставленную с группой в системе управления удостоверениями.

Проверка доступа для групп на GitHub

Если вы управляете доступом с помощью групп в системе управления удостоверениями, вы можете проверить, что пользователи получают нужный доступ. С помощью REST API можно сравнить членство в группах системы с GitHub. Дополнительные сведения см. в разделе [AUTOTITLE и Конечные точки REST API для внешних групп](/rest/teams/teams#get-a-team-by-name) в документации по REST API.

Общие сведения об ограничениях скорости для GitHub

Чтобы обеспечить доступность и надежность платформы, GitHub реализует ограничения скорости.

Без учета ограничений скорости крупные предприятия, подключенные с Enterprise Managed Users в первый раз, скорее всего, превышают пределы. Чтобы избежать превышения предела скорости GitHub, не назначайте более 1000 пользователей в час интеграции SCIM с идентификатором поставщика удостоверений. Если вы используете группы для назначения пользователей приложению IdP, не добавляйте более 1000 пользователей в каждую группу в час. При превышении этих пороговых значений попытки подготовки пользователей могут завершиться ошибкой, связанной с ограничением скорости. Журналы поставщика удостоверений можно проверить, не удалось ли выполнить подготовку SCIM или операции отправки из-за ошибки ограничения скорости. Ответ на неудачную попытку подготовки будет зависеть от поставщика удостоверений.

Дополнительные сведения см. в разделе Ограничения скорости для REST API.

Настройка потоковой передачи журналов аудита

В журнале аудита для вашего предприятия отображаются сведения о действиях в организации. Журнал аудита можно использовать для поддержки конфигурации SCIM. Дополнительные сведения см. в разделе Журнал аудита для предприятия.

Из-за объема событий в этом журнале GitHub сохраняет данные в течение 180 дней. Чтобы убедиться, что данные журнала аудита не теряются, а также просматривать более детализированные действия в журнале аудита, GitHub рекомендует настроить потоковую передачу журналов аудита. При потоковой передаче журнала аудита можно при необходимости передавать события для запросов API, включая запросы к конечным точкам REST API для подготовки SCIM. Дополнительные сведения см. в разделе Потоковая передача журнала аудита для предприятия.

Ограничение области маркера SCIM

Для повышения безопасности рекомендуется использовать personal access token (classic) с областью scim:enterprise действия, чтобы ограничить доступ маркера к конечным точкам REST API, необходимым для выполнения вызовов SCIM.

Если вы используете маркер с admin:enterprise областью, помните, что этот маркер предоставляет доступ ко всем действиям на предприятии. Вы можете заменить маркер на новый маркер только областью без нарушений scim:enterprise .

Общие сведения о последствиях отмены подготовки

Чтобы удалить доступ пользователя из GitHub, можно отправить запрос "обратимого отзыва" или "жесткого отзыва" поставщику SCIM. Жесткое отмена — это необратимое действие, которое окончательно приостанавливает учетную запись пользователя GitHub.

Перед реализацией интеграции API убедитесь, что вы понимаете типы отмены подготовки и эффекты, которые они имеют. Сведения о различных типах отмены подготовки, их эффектах и событиях журнала аудита, которые они создают, см. в разделе Отмена подготовки и восстановление пользователей с помощью SCIM.

Подготовка пользователей с помощью REST API

Чтобы подготовить, перечислить пользователей или управлять ими, выполните запросы к следующим конечным точкам REST API. Вы можете ознакомиться с связанными конечными точками API в документации по REST API и просмотреть примеры кода, а также просмотреть события журнала аудита, связанные с каждым запросом.

Прежде чем пользователь с удостоверением в системе управления удостоверениями может войти в систему вашей организации, необходимо создать соответствующего пользователя. Для подготовки новой учетной записи пользователя вашей организации не требуется доступная лицензия.

Общие сведения о поддерживаемых атрибутах для пользователей см. в документации по REST API.
Вы можете просмотреть подготовленных пользователей в пользовательском интерфейсе GitHub . Дополнительные сведения см. в разделе Просмотр пользователей в организации.

Действие	Способ	Конечная точка и дополнительные сведения	События в журнале аудита
Список всех подготовленных пользователей для вашей организации, который включает всех пользователей, которые обратимо отменяются, задав для `active`параметра значение `false` .	`GET`	`/scim/v2/enterprises/{enterprise}/Users`	Н/П
Создание пользователя. Ответ API содержит `id` поле для уникальной идентификации пользователя.	`POST`	`/scim/v2/enterprises/{enterprise}/Users`	`external_identity.provision` `user.create` Если запрос добавляет `enterprise_owner` роль, `business.add_admin` Если запрос добавляет `billing_manager` роль, `business.add_billing_manager` Если запрос выполнен успешно, `external_identity.scim_api_success` Если запрос завершается ошибкой, `external_identity.scim_api_failure`
Получите существующего пользователя в организации, используя `id` поле из `POST` запроса, отправленного для создания пользователя.	`GET`	`/scim/v2/enterprises/{enterprise}/Users/{scim_user_id}`	Н/П
Обновите все атрибуты существующего пользователя с помощью `id` поля из `POST` запроса, отправленного для создания пользователя. Обновление `active` до `false` обратимой отмены подготовки пользователя или `true` повторной активации пользователя. Дополнительные сведения см. в статье Soft-deprovisioning users with the REST API and Reactivating users with the REST API.	`PUT`	`/scim/v2/enterprises/{enterprise}/Users/{scim_user_id}`	`external_identity.update`, если не отмена или повторная подготовка Если запрос добавляет `enterprise_owner` роль, `business.add_admin` Если запрос добавляет объект `billing_manager`, `business.add_billing_manager` Если запрос удаляет `enterprise_owner` роль, `business.remove_admin` Если запрос удаляет `billing_manager` роль, `business.remove_billing_manager` Если запрос выполнен успешно, `external_identity.scim_api_success` Если запрос завершается ошибкой, `external_identity.scim_api_failure`
Обновите отдельный атрибут для существующего пользователя, используя `id` поле из `POST` запроса, отправленного для создания пользователя. Обновление `active` до `false` обратимой отмены подготовки пользователя или `true` повторной активации пользователя. Дополнительные сведения см. в статье Soft-deprovisioning users with the REST API and Reactivating users with the REST API.	`PATCH`	`/scim/v2/enterprises/{enterprise}/Users/{scim_user_id}`	`external_identity.update`, если не отмена или повторная подготовка Если запрос добавляет `enterprise_owner` роль, `business.add_admin` Если запрос добавляет объект `billing_manager`, `business.add_billing_manager` Если запрос удаляет `enterprise_owner` роль, `business.remove_admin` Если запрос удаляет `billing_manager` роль, `business.remove_billing_manager` Если запрос выполнен успешно, `external_identity.scim_api_success` Если запрос завершается ошибкой, `external_identity.scim_api_failure`
Чтобы окончательно приостановить существующего пользователя, вы можете жестко отменить подготовку пользователя. После жесткой отмены подготовки пользователь не может повторно активировать пользователя, и необходимо подготовить пользователя в качестве нового пользователя. Дополнительные сведения см. в статье "Жесткое отмена подготовки пользователей с помощью REST API".	`DELETE`	`/scim/v2/enterprises/{enterprise}/Users/{scim_user_id}`	`external_identity.deprovision` `user.remove_email` Если запрос выполнен успешно, `external_identity.scim_api_success` Если запрос завершается ошибкой, `external_identity.scim_api_failure`

Обратимое удаление пользователей с помощью REST API

Чтобы предотвратить вход пользователя в систему для доступа к вашей организации, вы можете обратимо отменить подготовку пользователя, отправив PUT``PATCH запрос на обновление поля active``falseпользователя /scim/v2/enterprises/{enterprise}/Users/{scim_user_id} на . При обратимой отмене подготовки пользователя GitHub зафиксирует запись login пользователя и email поля, а пользователь приостанавливается.

Повторная активация пользователей с помощью REST API

Чтобы разрешить пользователю с обратимой отменой входа в систему для доступа к вашей организации, отмените подписку пользователя, отправив PUT``PATCH запрос на /scim/v2/enterprises/{enterprise}/Users/{scim_user_id} это обновление поля activeпользователяtrue.

Жесткое отмена подготовки пользователей с помощью REST API

Внимание

Жесткое отмена — это необратимое действие, которое окончательно приостанавливает учетную запись пользователя GitHub. Ознакомьтесь с последствиями отмены подготовки.

Вы можете жестко отменить подготовку пользователя, отправив DELETE запрос /scim/v2/enterprises/{enterprise}/Users/{scim_user_id}в . Ваше предприятие будет хранить все ресурсы и комментарии, созданные пользователем.

Группы подготовки с помощью REST API

Для управления доступом к репозиториям в вашей организации можно использовать группы в системе управления удостоверениями для управления организацией и членством в команде для пользователей в организации. Вы можете ознакомиться с связанными конечными точками API в документации по REST API и просмотреть примеры кода, а также просмотреть события журнала аудита, связанные с каждым запросом.

Хотя для организации не требуется доступная лицензия для подготовки новой учетной записи пользователя, если вы подготавливаете группу, которая приводит к добавлению пользователей в организацию, необходимо иметь доступные лицензии для этих пользователей. Если ваше предприятие использует только Подписки Visual Studio с GitHub Enterprise, связанный пользователь должен быть назначен подписчику. Дополнительные сведения см. в разделе О подписках Visual Studio с GitHub Enterprise.

Общие сведения о поддерживаемых атрибутах для групп см. в документации ПО REST API.
Общие сведения о событиях журнала аудита, связанных с группами, см. в разделе События журнала аудита для вашего предприятия.
Вы можете просмотреть подготовленные группы в пользовательском интерфейсе GitHub . Дополнительные сведения см. в разделе Управление членством в группах поставщиков удостоверений.

Действие	Способ	Конечная точка и дополнительные сведения	Связанные события в журнале аудита
Список всех групп, определенных для вашей организации.	`GET`	`/scim/v2/enterprises/{enterprise}/Groups`	Н/П
Чтобы определить новую группу поставщика удостоверений для предприятия, создайте группу. Ответ API содержит `id` поле для уникальной идентификации группы.	`POST`	`/scim/v2/enterprises/{enterprise}/Groups`	`external_group.provision` `external_group.update_display_name` Если запрос включал список пользователей, `external_group.add_member` Если запрос выполнен успешно, `external_group.scim_api_success` Если запрос завершается ошибкой, `external_group.scim_api_failure`
Получите существующую группу для вашего предприятия с помощью id``POST запроса, отправленного для создания группы.	`GET`	`/scim/v2/enterprises/{enterprise}/Groups/{scim_group_id}`	Н/П
Обновите все атрибуты для существующей группы.	`PUT`	`/scim/v2/enterprises/{enterprise}/Groups/{scim_group_id}`	`external_group.update` Если запрос обновляет имя группы, `external_group.update_display_name` Если запрос добавляет пользователя в группу, `external_group.add_member` Если запрос удаляет пользователя из группы, `external_group.remove_member` Если запрос выполнен успешно, `external_group.scim_api_success` Если запрос завершается ошибкой, `external_group.scim_api_failure` Дополнительные события могут отображаться в журнале аудита в зависимости от того, является ли пользователь членом организации с командой, связанной с группой поставщика удостоверений. Дополнительные сведения см. в разделе "Дополнительные события журнала аудита" для изменений в группах поставщика удостоверений.
Обновите отдельный атрибут для существующей группы.	`PATCH`	`/scim/v2/enterprises/{enterprise}/Groups/{scim_group_id}`	`external_group.update` Если запрос обновляет имя группы, `external_group.update_display_name` Если запрос добавляет пользователя в группу, `external_group.add_member` Если запрос удаляет пользователя из группы, `external_group.remove_member` Если запрос выполнен успешно, `external_group.scim_api_success` Если запрос завершается ошибкой, `external_group.scim_api_failure` Дополнительные события могут отображаться в журнале аудита в зависимости от того, является ли пользователь членом организации с командой, связанной с группой поставщика удостоверений. Дополнительные сведения см. в разделе "Дополнительные события журнала аудита" для изменений в группах поставщика удостоверений.
Полностью удалите существующую группу.	`DELETE`	`/scim/v2/enterprises/{enterprise}/Groups/{scim_group_id}`	`external_group.delete` Если запрос удаляет группу, связанную с командой в организации, в которой пользователь не имеет другого членства в команде, `org.remove_member` Если запрос удаляет группу, связанную с командой в организации, в которой пользователь имеет другое членство в команде, `team.remove_member` Если запрос выполнен успешно, `external_group.scim_api_success` Если запрос завершается ошибкой, `external_group.scim_api_failure`

Дополнительные события журнала аудита для изменений в группах поставщика удостоверений

Если вы обновляете членов существующей группы с помощью PUT или PATCH запроса /scim/v2/enterprises/{enterprise}/Groups/{scim_group_id}на GitHub может добавить пользователя в организацию или удалить пользователя из организации в зависимости от текущего членства в организации. Если пользователь уже является членом по крайней мере одной команды в организации, пользователь является членом организации. Если пользователь не является членом каких-либо команд в организации, пользователь может также не быть членом организации.

Если запрос обновляет группу, связанную с командой в организации, в которой пользователь еще не является членом, кроме external_group.updateтого, в журнале аудита отображаются следующие события:

org.add_member
Если запрос добавляет пользователя в группу, связанную с командой в организации, где пользователь еще не является участником, org.add_member
Если запрос добавляет пользователя в группу, связанную с командой в организации, team.add_member

Если запрос обновляет группу, связанную с командой в организации, в которой пользователь уже является членом, а также external_group.updateв журнале аудита отображаются следующие события:

Если запрос удаляет пользователя из группы, связанной с командой в организации, и команда не является последней командой в организации, где пользователь является членом, team.remove_member
Если запрос удаляет пользователя из группы, связанной с последней командой в организации, где пользователь уже является членом, org.remove_member

Переход на новый поставщик SCIM

После настройки подготовки SCIM для предприятия может потребоваться перенести его в новый поставщик SCIM. Дополнительные сведения см. в разделе Перенос предприятия в новый поставщик удостоверений или клиент.

Устранение неполадок при подготовке SCIM

Если ваши запросы к REST API ограничены скоростью, дополнительные сведения см. в разделе "Общие сведения о ограничениях скорости" на GitHub.
Все запросы SCIM, которые GitHub получают, за исключением успешных HTTP-запросов GET , создадут событие журнала аудита. Эти журналы содержат полезные сведения о результатах запроса, полезных данных и любых ошибках. Эти журналы можно использовать для определения того, получили ли данные GitHub запрос SCIM и устраняют неполадки API.
- Чтобы определить, подготовлен ли пользователь, можно использовать следующий запрос журнала аудита: action:external_identity.provision user:USERNAME_SHORTCODE
- Если вы не нашли пользователя с помощью приведенного выше запроса, можно найти action:external_identity.scim_api_failure события на дату, которую вы ожидали получить.
Если запрос SCIM не удается определить причину, проверьте состояние системы управления удостоверениями, чтобы убедиться, что службы были доступны. Кроме того, проверьте страницу состояния GitHub. Дополнительные сведения см. в разделе О поддержке GitHub.
Если запрос на подготовку пользователя завершается ошибкой 400 , а сообщение об ошибке в журнале системы управления удостоверениями указывает на проблемы с владением учетной записью или форматированием имени пользователя, просмотрите Рекомендации по использованию имени пользователя для внешней проверки подлинности.
После успешной проверки подлинности GitHub связывает пользователя, прошедшего проверку подлинности на удостоверение, подготовленное SCIM. Уникальные идентификаторы для проверки подлинности и подготовки должны соответствовать. Дополнительные сведения см. в разделе Конечные точки REST API для SCIM. Вы также можете просмотреть это сопоставление на GitHub. См. Просмотр сведений о SAML-доступе пользователей к предприятию и управление ими.
При управлении доступом с помощью групп в системе управления удостоверениями можно устранить неполадки с помощью REST API или веб-интерфейса для GitHub.
- С помощью REST API можно сравнить членство в группах системы управления удостоверениями с GitHub. См. раздел [AUTOTITLE и Конечные точки REST API для внешних групп](/rest/teams/teams#get-a-team-by-name).
- Дополнительные сведения об устранении неполадок с помощью веб-интерфейса см. в разделе Устранение неполадок членства в команде с группами поставщиков удостоверений.

Дополнительные рекомендации по устранению неполадок см. в разделе Устранение неполадок с управлением удостоверениями и доступом для предприятия.