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

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

В этой статье

Note

SCIM для GitHub Enterprise Server в настоящее время находится в общедоступной бета-версии и подлежит изменению. GitHub рекомендует сначала тестировать с помощью промежуточный экземпляр. См. раздел "Настройка промежуточного экземпляра".

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

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

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

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

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

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

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

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

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

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

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

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

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

  • Необходимо выполнить шаги 1–3 в autoTITLE.

    • Для проверки подлинности запросов к REST API необходимо использовать personal access token (classic), созданных для встроенного пользователя установки.

  • Чтобы подготовить пользователей и группы с помощью REST API GitHub, ваша система управления удостоверениями должна поддерживать стандарт SCIM 2.0. Дополнительные сведения см. на веб-сайте IETF ниже.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Проверка доступа для групп в 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. Дополнительные сведения см. в разделе Потоковая передача журнала аудита для предприятия.

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

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

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

  • Общие сведения о поддерживаемых атрибутах для пользователей см. в разделе "SCIM" документации по REST API.
  • Вы можете просматривать подготовленных пользователей в веб-интерфейсе для GitHub Enterprise Server. Дополнительные сведения см. в разделе Просмотр пользователей в организации.
ДействиеСпособКонечная точка и дополнительные сведенияСобытия в журнале аудита
Список всех подготовленных пользователей для вашей организации, который включает всех пользователей, которые обратимо отменяются, задав для falseпараметра значение active .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 повторной активации пользователя. Дополнительные сведения см. в статье "Обратимое отмена подготовки пользователей с помощью REST API" и "Повторное активация пользователей с помощью 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 повторной активации пользователя. Дополнительные сведения см. в статье "Обратимое отмена подготовки пользователей с помощью REST API" и "Повторное активация пользователей с помощью 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

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

При обратимой отмене подготовки пользователя external_identity.update событие не отображается в журнале аудита. В журнале аудита отображаются следующие события:

  • user.suspend
  • user.remove_email
  • user.rename
  • external_identity.deprovision
  • Если запрос выполнен успешно, external_identity.scim_api_success
  • Если запрос завершается ошибкой, external_identity.scim_api_failure

Вы можете просмотреть всех приостановленных пользователей для вашего предприятия. Дополнительные сведения см. в разделе "Просмотр пользователей в организации".

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

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

При повторной активации пользователя external_identity.update событие не отображается в журнале аудита. В журнале аудита отображаются следующие события:

  • user.unsuspend
  • user.remove_email
  • user.rename
  • external_identity.provision
  • Если запрос выполнен успешно, external_identity.scim_api_success
  • Если запрос завершается ошибкой, external_identity.scim_api_failure

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

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

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

  • Записи пользователя login и email поля скрываются.
  • Отображаемое имя пользователя имеет пустую строку.
  • GitHub Enterprise Server удаляет все атрибуты SCIM пользователя, сообщения электронной почты, ключи SSH, personal access tokensи ключи GPG.
  • Учетная запись пользователя на GitHub Enterprise Server приостановлена, а проверка подлинности для входа в учетную запись завершится ошибкой.

Для повторной подготовки пользователя необходимо использовать POST метод для создания нового пользователя. Новый пользователь может повторно использовать устаревший пользователь login. Если адреса электронной почты жестко отозванного пользователя и нового пользователя совпадают, GitHub Enterprise Server будет атрибутировать существующие фиксации Git, связанные с адресом электронной почты новому пользователю. Существующие ресурсы и комментарии, созданные исходным пользователем, не будут связаны с новым пользователем.

Группы подготовки с помощью 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 или PATCH запроса /scim/v2/Groups/{scim_group_id}на GitHub Enterprise Server может добавить пользователя в организацию или удалить пользователя из организации в зависимости от текущего членства пользователя в организации. Если пользователь уже является членом по крайней мере одной команды в организации, пользователь является членом организации. Если пользователь не является членом каких-либо команд в организации, пользователь может также не быть членом организации.

Если запрос обновляет группу, связанную с командой в организации, в которой пользователь еще не является членом, кроме 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".

  • Если включить потоковую передачу журналов аудита и потоковую передачу событий для запросов API, можно просмотреть все запросы к конечным точкам REST API для подготовки SCIM, отфильтровав события от EnterpriseUsersScim или EnterpriseGroupsScim контроллеров.

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

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

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

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

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