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

Управление жизненным циклом учетных записей пользователей от поставщика удостоверений с помощью GitHubREST API для системы управления междоменной идентификацией (SCIM).

В этой статье

Сведения о подготовке SCIM GitHub Enterprise Server

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

  • Проверка подлинности единого входа, реализующего язык разметки утверждений безопасности (SAML) 2.0
  • Управление жизненным циклом пользователей с помощью system for Cross-domain Identity Management (SCIM)

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

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

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

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

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

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

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

Внимание

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

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

Чтобы реализовать SCIM с помощью REST API, общие предварительные требования для использования SCIM при GitHub Enterprise Server применении. См. раздел "Предварительные требования" в Настройка SCIM-предоставления пользователей Enterprise для управления пользователями.

Кроме того, применяются следующие предварительные требования:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Если администратор сайта включил ограничения скорости для вашего экземпляра, при первой подготовке пользователей могут возникнуть ошибки. Журналы поставщика удостоверений можно проверить, не удалось ли выполнить подготовку 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 . Дополнительные сведения см. в разделе Просмотр пользователей в организации.
  • Корпоративные администраторы с доступом CLI могут экспортировать полный CSV-файл подготовленных удостоверений пользователей SCIM с помощью средства ghe-scim-identities-csv .
ДействиеСпособКонечная точка и дополнительные сведенияСобытия в журнале аудита
Список всех подготовленных пользователей для вашей организации, который включает всех пользователей, которые обратимо отменяются, задав для activeпараметра значение false .GET/scim/v2/UsersН/П
Создание пользователя. Ответ API содержит id поле для уникальной идентификации пользователя.POST/scim/v2/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/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/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/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/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/Users/{scim_user_id} на . При обратимой отмене подготовки пользователя GitHub зафиксирует запись login пользователя и email поля, а пользователь приостанавливается.

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

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

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

Внимание

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

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

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

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

Хотя для организации не требуется доступная лицензия для подготовки новой учетной записи пользователя, если вы подготавливаете группу, которая приводит к добавлению пользователей в организацию, необходимо иметь доступные лицензии для этих пользователей.

ДействиеСпособКонечная точка и дополнительные сведенияСвязанные события в журнале аудита
Список всех групп, определенных для вашей организации.GET/scim/v2/GroupsН/П
Чтобы определить новую группу поставщика удостоверений для предприятия, создайте группу. Ответ API содержит id поле для уникальной идентификации группы.POST/scim/v2/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/Groups/{scim_group_id}Н/П
Обновите все атрибуты для существующей группы.PUT/scim/v2/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/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/Groups/{scim_group_id}
  • external_group.delete
  • Если запрос удаляет группу, связанную с командой в организации, в которой пользователь не имеет другого членства в команде, org.remove_member
  • Если запрос удаляет группу, связанную с командой в организации, в которой пользователь имеет другое членство в команде, team.remove_member
  • Если запрос выполнен успешно, external_group.scim_api_success
  • Если запрос завершается ошибкой, external_group.scim_api_failure

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

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

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

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

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

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

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

  • Если ваши запросы к REST API ограничены скоростью, дополнительные сведения см. в разделе "Общие сведения об ограничениях скорости".GitHub

  • Все запросы SCIM, получающие GitHub , за исключением успешных HTTP-запросов GET , будут создавать событие журнала аудита . Эти журналы содержат полезные сведения о результатах запроса, полезных данных и любых ошибках. Эти журналы можно использовать для определения того, получен ли GitHub запрос SCIM и устранять сбои API.

    • Чтобы определить, подготовлен ли пользователь, можно использовать следующий запрос журнала аудита: action:external_identity.provision user:USERNAME
    • Если вы не нашли пользователя с помощью приведенного выше запроса, можно найти action:external_identity.scim_api_failure события на дату, которую вы ожидали получить.

  • Если запрос SCIM не удается определить причину, проверьте состояние системы управления удостоверениями, чтобы убедиться, что службы были доступны.

  • Если запрос на подготовку пользователя завершается ошибкой 400 , а сообщение об ошибке в журнале системы управления удостоверениями указывает на проблемы с владением учетной записью или форматированием имени пользователя, просмотрите Рекомендации по использованию имени пользователя для внешней проверки подлинности.

  • После успешной проверки подлинности связывает пользователя, прошедшего проверку подлинности, GitHub к удостоверению, подготовленному SCIM. Уникальные идентификаторы для проверки подлинности и подготовки должны соответствовать. Для получения дополнительной информации см. Конечные точки REST API для SCIM.

  • Если вы управляете доступом с помощью групп в системе управления удостоверениями, вы можете устранить неполадки с помощью REST API или веб-интерфейса.GitHub

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