Note
SCIM для GitHub Enterprise Server в настоящее время находится в beta и подлежит изменению. 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
- Подготовка пользователей перед подготовкой групп
- Проверка доступа для групп в GitHub
- Общие сведения об ограничениях скорости для 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.
Чтобы управлять членством в группе с группами в системе управления удостоверениями, необходимо последовательно выполнить следующие действия.
- Подготовка учетных записей пользователей в GitHub Enterprise Server.
- Подготовьте группу для GitHub Enterprise Server.
- Обновите членство в группе в системе управления удостоверениями.
- Создайте команду на 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 |
|
Получите существующего пользователя в организации, используя 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} |
|
Обновите отдельный атрибут для существующего пользователя, используя id поле из POST запроса, отправленного для создания пользователя. Обновление active до false обратимой отмены подготовки пользователя или true повторной активации пользователя. Дополнительные сведения см. в статье "Обратимое отмена подготовки пользователей с помощью REST API" и "Повторное активация пользователей с помощью REST API". | PATCH | /scim/v2/Users/{scim_user_id} |
|
Чтобы полностью удалить существующего пользователя, вы можете жестко отменить подготовку пользователя. После жесткой отмены подготовки пользователь не может повторно активировать пользователя, и необходимо подготовить пользователя в качестве нового пользователя. Дополнительные сведения см. в статье "Жесткое отмена подготовки пользователей с помощью REST API". | DELETE | /scim/v2/Users/{scim_user_id} |
|
Обратимое удаление пользователей с помощью 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 и просмотреть примеры кода, а также просмотреть события журнала аудита, связанные с каждым запросом.
Хотя для организации не требуется доступная лицензия для подготовки новой учетной записи пользователя, если вы подготавливаете группу, которая приводит к добавлению пользователей в организацию, необходимо иметь доступные лицензии для этих пользователей.
- Общие сведения о поддерживаемых атрибутах для групп см. в документации по REST API в разделе "SCIM".
- Общие сведения о событиях журнала аудита, связанных с группами, см. в разделе "События журнала аудита для вашего предприятия".
- Вы можете просматривать подготовленные группы в веб-интерфейсе для GitHub Enterprise Server. Дополнительные сведения см. в разделе Управление членством в группах поставщиков удостоверений.
Действие | Способ | Конечная точка и дополнительные сведения | Связанные события в журнале аудита |
---|---|---|---|
Список всех групп, определенных для вашей организации. | GET | /scim/v2/Groups | Н/П |
Чтобы определить новую группу поставщика удостоверений для предприятия, создайте группу. Ответ API содержит id поле для уникальной идентификации группы. | POST | /scim/v2/Groups |
|
Получите существующую группу для вашего предприятия с помощью id POST запроса, отправленного для создания группы. | GET | /scim/v2/Groups/{scim_group_id} | Н/П |
Обновите все атрибуты для существующей группы. | PUT | /scim/v2/Groups/{scim_group_id} |
|
Обновите отдельный атрибут для существующей группы. | PATCH | /scim/v2/Groups/{scim_group_id} |
|
Полностью удалите существующую группу. | DELETE | /scim/v2/Groups/{scim_group_id} |
|
Дополнительные события журнала аудита для изменений в группах поставщика удостоверений
Если вы обновляете членов существующей группы с помощью 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.
- С помощью REST API можно сравнить членство в группах системы управления удостоверениями с GitHub. См. раздел "[AUTOTITLE" и "Конечные точки REST API для внешних групп](/rest/teams/teams#get-a-team-by-name)".
- Дополнительные сведения об устранении неполадок с помощью веб-интерфейса см. в разделе "Устранение неполадок членства в команде с группами поставщиков удостоверений".
Дополнительные рекомендации по устранению неполадок см. в разделе "Устранение неполадок с управлением удостоверениями и доступом для предприятия".