Конечные точки REST API для SCIM
Используйте REST API для управления доступом членов организации GitHub и управления ими с помощью SCIM.
Примечание.
Эта операция позволяет подготовить доступ к организации на GitHub Enterprise Cloud с помощью SCIM. Операция недоступна для использования с Enterprise Managed Users. Дополнительные сведения о подготовке управляемые учетные записи пользователей с помощью SCIM см. в разделе Конечные точки REST API для SCIM.
Общие сведения о SCIM
Подготовка SCIM для организаций
Эти конечные точки используются поставщиками удостоверений с поддержкой SCIM для автоматизации подготовки GitHub и основаны на версии 2.0 стандарта SCIM. Поставщики удостоверений должны использовать базовый URL-адрес https://api.github.com/scim/v2/organizations/{org}/
для конечных точек SCIM GitHub SCIM.
Примечание.
- Эти конечные точки доступны только для отдельных организаций, использующих GitHub Enterprise Cloud с включенным единым входом SAML. Дополнительные сведения о SCIM см. в разделе Сведения о SCIM для организаций. Дополнительные сведения о авторизации маркера для организации единого входа SAML см. в разделе Проверка подлинности в REST API.
- Эти конечные точки нельзя использовать с учетной записью предприятия или с организация с управляемыми пользователями.
Проверка подлинности
Для использования этих конечных точек необходимо пройти проверку подлинности в качестве владельца организации GitHub . REST API ожидает, что маркер доступа пользователя OAuth 2.0 (например, GitHub App маркер доступа пользователя) будет включен в Authorization
заголовок. Если для проверки подлинности используется personal access token (classic), она должна иметь admin:org
область действия, а также авторизовать ее для использования с организацией единого входа SAML.
Сопоставление атрибутов SAML и SCIM
Чтобы успешно связать учетную запись пользователя GitHub с удостоверением SCIM в организации, определенные атрибуты из ответа SAML поставщика удостоверений и вызова подготовки API SCIM должны соответствовать пользователю.
Идентификатор Microsoft Entra для SAML
При использовании идентификатора записи (ранее известного как Azure AD) для SAML необходимо соответствовать следующему атрибуту SAML и атрибуту SCIM.
Атрибут SAML | Сопоставление атрибута SCIM |
---|---|
http://schemas.microsoft.com/identity/claims/objectidentifier | externalId |
Другие поставщики удостоверений для SAML
При использовании других поставщиков удостоверений для SAML необходимо соответствовать следующим утверждениям SAML и атрибуту SCIM.
Атрибут SAML | Сопоставление атрибута SCIM |
---|---|
NameID | userName |
Существует два разных способа: учетная запись пользователя GitHub может связаться с удостоверением SCIM в организации при совпадении этих атрибутов SAML/SCIM:
-
Для пользователей, которые еще не являются членами организации:
- IdP отправляет вызов подготовки SCIM к GitHub для пользователя, который не является членом организации. Это создает приглашение организации и удостоверение SCIM без связи в организации.
- Пользователь проходит проверку подлинности через SAML в организации.
- GitHub автоматически связывает удостоверение SAML и SCIM с новой учетной записью пользователя в организации.
-
Для существующих членов организации:
- IdP отправляет вызов подготовки SCIM к GitHub для пользователя, который уже является членом организации.
- Если у члена организации нет связанного удостоверения SAML в организации, это создает приглашение организации и удостоверение SCIM без связи в организации. Пользователь проходит проверку подлинности с помощью SAML в организации, чтобы связать удостоверение SAML и SCIM.
- Если у члена организации есть связанное удостоверение SAML в организации, GitHub автоматически связывает удостоверение SCIM с существующей учетной записью пользователя в организации. Приглашение организации не создается.
Обеспечение правильной привязки пользователя к удостоверению SCIM в организации может помочь предотвратить непредвиденные проблемы с отменой scIM при удалении доступа пользователя к приложению на стороне поставщика удостоверений. Дополнительные сведения об аудите связанных удостоверений SCIM в организации см. в разделе Устранение неполадок с управлением удостоверениями и доступом для вашей организации
Поддерживаемые атрибуты пользователя SCIM
Имя. | Тип | Описание |
---|---|---|
userName | string | Имя пользователя. |
name.givenName | string | Имя пользователя. |
name.familyName | string | Фамилия пользователя. |
emails | array | Список адресов электронной почты пользователя. |
externalId | string | Этот идентификатор создается поставщиком SAML и используется этим поставщиком в качестве уникального идентификатора для сопоставления с пользователем GitHub. externalID для пользователя можно найти в поставщике SAML. Или используйте конечную точку Список подготовленных удостоверений SCIM и выполните фильтрацию по другим известным атрибутам, таким как имя пользователя или адрес электронной почты пользователя GitHub. |
id | string | Идентификатор, созданный конечной точкой SCIM GitHub. |
active | boolean | Указывает, является ли удостоверение активным (true), или оно должно быть отозвано (false). |
Примечание.
Эти конечные точки чувствительны к регистру. Например, первая буква в конечной точке Users
должна быть прописной:
GET /scim/v2/organizations/{org}/Users/{scim_user_id}
List SCIM provisioned identities
Retrieves a paginated list of all provisioned organization members, including pending invitations. If you provide the filter
parameter, the resources for all matching provisions members are returned.
The returned list of SCIM provisioned identities from the GitHub Enterprise Cloud might not always match the organization or enterprise member list. Here is why that can occur:
- When an organization invitation is generated by a SCIM integration, this creates an unlinked SCIM identity in the organization. When a user logs into their GitHub user account, visits the organization, and successfully authenticates via SAML, they get added as an organization member and linked to their SAML/SCIM identity in the organization. If the user does not do this, the SCIM identity will remain in the organization, not linked to any organization member.
- A user's organization membership (inviting and removing a user to/from the organization) should only be managed by a SCIM integration when this is configured for a GitHub organization. If a GitHub user who has a linked SCIM identity is removed from the organization using the GitHub UI or non-SCIM API, as opposed to the SCIM integration, this can leave behind a stale SAML/SCIM identity in the organization for the user.
Подробные маркеры доступа для "List SCIM provisioned identities
Эта конечная точка работает со следующими точными типами маркеров:
- Маркеры доступа пользователей приложения GitHub
- Маркеры доступа к установке приложений GitHub
- Точные личные маркеры доступа
Маркер с точной детализацией должен иметь следующий набор разрешений.:
- "Members" organization permissions (read)
Параметры для "List SCIM provisioned identities"
Имя., Тип, Description |
---|
accept string Setting to |
Имя., Тип, Description |
---|
org string Обязательное полеThe organization name. The name is not case sensitive. |
Имя., Тип, Description |
---|
startIndex integer Used for pagination: the index of the first result to return. |
count integer Used for pagination: the number of results to return. |
filter string Filters results using the equals query parameter operator (
To filter results for the identity with the email
|
Коды состояния http-ответа для "List SCIM provisioned identities"
Код состояния | Описание |
---|---|
200 | OK |
304 | Not modified |
400 | Bad request |
403 | Forbidden |
404 | Resource not found |
429 | Too many requests |
Примеры кода для "List SCIM provisioned identities"
Если вы обращаетесь к GitHub в GHE.com, замените api.github.com
выделенный поддомен api.SUBDOMAIN.ghe.com
предприятия.
Примеры запросов
curl -L \
-H "Accept: application/scim+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
https://api.github.com/scim/v2/organizations/ORG/Users
Response with filter
Status: 200
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"totalResults": 1,
"itemsPerPage": 1,
"startIndex": 1,
"Resources": [
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"id": "5fc0c238-1112-11e8-8e45-920c87bdbd75",
"externalId": "00u1dhhb1fkIGP7RL1d8",
"userName": "octocat@github.com",
"displayName": "Mona Octocat",
"name": {
"givenName": "Mona",
"familyName": "Octocat",
"formatted": "Mona Octocat"
},
"emails": [
{
"value": "octocat@github.com",
"primary": true
}
],
"active": true,
"meta": {
"resourceType": "User",
"created": "2018-02-13T15:05:24.000-08:00",
"lastModified": "2018-02-13T15:05:55.000-08:00",
"location": "https://api.github.com/scim/v2/organizations/octo-org/Users/5fc0c238-1112-11e8-8e45-920c87bdbd75"
}
}
]
}
Provision and invite a SCIM user
Provisions organization membership for a user, and sends an activation email to the email address. If the user was previously a member of the organization, the invitation will reinstate any former privileges that the user had. For more information about reinstating former members, see "Reinstating a former member of your organization."
Подробные маркеры доступа для "Provision and invite a SCIM user
Эта конечная точка работает со следующими точными типами маркеров:
- Маркеры доступа пользователей приложения GitHub
- Маркеры доступа к установке приложений GitHub
- Точные личные маркеры доступа
Маркер с точной детализацией должен иметь следующий набор разрешений.:
- "Members" organization permissions (write)
Параметры для "Provision and invite a SCIM user"
Имя., Тип, Description |
---|
accept string Setting to |
Имя., Тип, Description |
---|
org string Обязательное полеThe organization name. The name is not case sensitive. |
Имя., Тип, Description | ||||
---|---|---|---|---|
userName string Обязательное полеConfigured by the admin. Could be an email, login, or username | ||||
displayName string The name of the user, suitable for display to end-users | ||||
name object Обязательное поле | ||||
Properties of |
Имя., Тип, Description |
---|
givenName string Обязательное поле |
familyName string Обязательное поле |
formatted string |
emails
array of objects Обязательное полеuser emails
Properties of emails
Имя., Тип, Description |
---|
value string Обязательное поле |
primary boolean |
type string |
schemas
array of strings externalId
string groups
array of strings active
boolean Коды состояния http-ответа для "Provision and invite a SCIM user"
Код состояния | Описание |
---|---|
201 | Created |
304 | Not modified |
400 | Bad request |
403 | Forbidden |
404 | Resource not found |
409 | Conflict |
500 | Internal server error |
Примеры кода для "Provision and invite a SCIM user"
Если вы обращаетесь к GitHub в GHE.com, замените api.github.com
выделенный поддомен api.SUBDOMAIN.ghe.com
предприятия.
Пример запроса
curl -L \
-X POST \
-H "Accept: application/scim+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
https://api.github.com/scim/v2/organizations/ORG/Users \
-d '{"userName":"mona.octocat@okta.example.com","externalId":"a7d0f98382","name":{"givenName":"Monalisa","familyName":"Octocat","formatted":"Monalisa Octocat"},"emails":[{"value":"mona.octocat@okta.example.com","primary":true},{"value":"monalisa@octocat.github.com"}]}'
Response
Status: 201
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"id": "edefdfedf-050c-11e7-8d32",
"externalId": "a7d0f98382",
"userName": "mona.octocat@okta.example.com",
"displayName": "Monalisa Octocat",
"name": {
"givenName": "Monalisa",
"familyName": "Octocat",
"formatted": "Monalisa Octocat"
},
"emails": [
{
"value": "mona.octocat@okta.example.com",
"primary": true
},
{
"value": "monalisa@octocat.github.com"
}
],
"active": true,
"meta": {
"resourceType": "User",
"created": "2017-03-09T16:11:13-05:00",
"lastModified": "2017-03-09T16:11:13-05:00",
"location": "https://api.github.com/scim/v2/organizations/octo-org/Users/edefdfedf-050c-11e7-8d32"
}
}
Get SCIM provisioning information for a user
Gets SCIM provisioning information for a user.
Подробные маркеры доступа для "Get SCIM provisioning information for a user
Эта конечная точка работает со следующими точными типами маркеров:
- Маркеры доступа пользователей приложения GitHub
- Маркеры доступа к установке приложений GitHub
- Точные личные маркеры доступа
Маркер с точной детализацией должен иметь следующий набор разрешений.:
- "Members" organization permissions (read)
Параметры для "Get SCIM provisioning information for a user"
Имя., Тип, Description |
---|
accept string Setting to |
Имя., Тип, Description |
---|
org string Обязательное полеThe organization name. The name is not case sensitive. |
scim_user_id string Обязательное полеThe unique identifier of the SCIM user. |
Коды состояния http-ответа для "Get SCIM provisioning information for a user"
Код состояния | Описание |
---|---|
200 | OK |
304 | Not modified |
403 | Forbidden |
404 | Resource not found |
Примеры кода для "Get SCIM provisioning information for a user"
Если вы обращаетесь к GitHub в GHE.com, замените api.github.com
выделенный поддомен api.SUBDOMAIN.ghe.com
предприятия.
Пример запроса
curl -L \
-H "Accept: application/scim+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
https://api.github.com/scim/v2/organizations/ORG/Users/SCIM_USER_ID
Response
Status: 200
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"id": "edefdfedf-050c-11e7-8d32",
"externalId": "a7d0f98382",
"userName": "mona.octocat@okta.example.com",
"displayName": "Monalisa Octocat",
"name": {
"givenName": "Monalisa",
"familyName": "Octocat",
"formatted": "Monalisa Octocat"
},
"emails": [
{
"value": "mona.octocat@okta.example.com",
"primary": true
},
{
"value": "monalisa@octocat.github.com"
}
],
"active": true,
"meta": {
"resourceType": "User",
"created": "2017-03-09T16:11:13-05:00",
"lastModified": "2017-03-09T16:11:13-05:00",
"location": "https://api.github.com/scim/v2/organizations/octo-org/Users/edefdfedf-050c-11e7-8d32"
}
}
Update a provisioned organization membership
Replaces an existing provisioned user's information. You must provide all the information required for the user as if you were provisioning them for the first time. Any existing user information that you don't provide will be removed. If you want to only update a specific attribute, use the Update an attribute for a SCIM user endpoint instead.
You must at least provide the required values for the user: userName
, name
, and emails
.
Warning
Setting active: false
removes the user from the organization, deletes the external identity, and deletes the associated {scim_user_id}
.
Подробные маркеры доступа для "Update a provisioned organization membership
Эта конечная точка работает со следующими точными типами маркеров:
- Маркеры доступа пользователей приложения GitHub
- Маркеры доступа к установке приложений GitHub
- Точные личные маркеры доступа
Маркер с точной детализацией должен иметь следующий набор разрешений.:
- "Members" organization permissions (write)
Параметры для "Update a provisioned organization membership"
Имя., Тип, Description |
---|
accept string Setting to |
Имя., Тип, Description |
---|
org string Обязательное полеThe organization name. The name is not case sensitive. |
scim_user_id string Обязательное полеThe unique identifier of the SCIM user. |
Имя., Тип, Description | ||||
---|---|---|---|---|
schemas array of strings | ||||
displayName string The name of the user, suitable for display to end-users | ||||
externalId string | ||||
groups array of strings | ||||
active boolean | ||||
userName string Обязательное полеConfigured by the admin. Could be an email, login, or username | ||||
name object Обязательное поле | ||||
Properties of |
Имя., Тип, Description |
---|
givenName string Обязательное поле |
familyName string Обязательное поле |
formatted string |
emails
array of objects Обязательное полеuser emails
Properties of emails
Имя., Тип, Description |
---|
type string |
value string Обязательное поле |
primary boolean |
Коды состояния http-ответа для "Update a provisioned organization membership"
Код состояния | Описание |
---|---|
200 | OK |
304 | Not modified |
403 | Forbidden |
404 | Resource not found |
Примеры кода для "Update a provisioned organization membership"
Если вы обращаетесь к GitHub в GHE.com, замените api.github.com
выделенный поддомен api.SUBDOMAIN.ghe.com
предприятия.
Пример запроса
curl -L \
-X PUT \
-H "Accept: application/scim+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
https://api.github.com/scim/v2/organizations/ORG/Users/SCIM_USER_ID \
-d '{"userName":"mona.octocat@okta.example.com","externalId":"a7d0f98382","name":{"givenName":"Monalisa","familyName":"Octocat","formatted":"Monalisa Octocat"},"emails":[{"value":"mona.octocat@okta.example.com","primary":true}]}'
Response
Status: 200
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"id": "edefdfedf-050c-11e7-8d32",
"externalId": "a7d0f98382",
"userName": "mona.octocat@okta.example.com",
"displayName": "Monalisa Octocat",
"name": {
"givenName": "Monalisa",
"familyName": "Octocat",
"formatted": "Monalisa Octocat"
},
"emails": [
{
"value": "mona.octocat@okta.example.com",
"primary": true
},
{
"value": "monalisa@octocat.github.com"
}
],
"active": true,
"meta": {
"resourceType": "User",
"created": "2017-03-09T16:11:13-05:00",
"lastModified": "2017-03-09T16:11:13-05:00",
"location": "https://api.github.com/scim/v2/organizations/octo-org/Users/edefdfedf-050c-11e7-8d32"
}
}
Update an attribute for a SCIM user
Allows you to change a provisioned user's individual attributes. To change a user's values, you must provide a specific Operations
JSON format that contains at least one of the add
, remove
, or replace
operations. For examples and more information on the SCIM operations format, see the SCIM specification.
Note
Complicated SCIM path
selectors that include filters are not supported. For example, a path
selector defined as "path": "emails[type eq \"work\"]"
will not work.
Warning
If you set active:false
using the replace
operation (as shown in the JSON example below), it removes the user from the organization, deletes the external identity, and deletes the associated :scim_user_id
.
{
"Operations":[{
"op":"replace",
"value":{
"active":false
}
}]
}
Подробные маркеры доступа для "Update an attribute for a SCIM user
Эта конечная точка работает со следующими точными типами маркеров:
- Маркеры доступа пользователей приложения GitHub
- Маркеры доступа к установке приложений GitHub
- Точные личные маркеры доступа
Маркер с точной детализацией должен иметь следующий набор разрешений.:
- "Members" organization permissions (write)
Параметры для "Update an attribute for a SCIM user"
Имя., Тип, Description |
---|
accept string Setting to |
Имя., Тип, Description |
---|
org string Обязательное полеThe organization name. The name is not case sensitive. |
scim_user_id string Обязательное полеThe unique identifier of the SCIM user. |
Имя., Тип, Description | ||||
---|---|---|---|---|
schemas array of strings | ||||
Operations array of objects Обязательное полеSet of operations to be performed | ||||
Properties of |
Имя., Тип, Description |
---|
op string Обязательное полеВозможные значения: |
path string |
value object or array or string |
Коды состояния http-ответа для "Update an attribute for a SCIM user"
Код состояния | Описание |
---|---|
200 | OK |
304 | Not modified |
400 | Bad request |
403 | Forbidden |
404 | Resource not found |
429 | Too Many Requests |
Примеры кода для "Update an attribute for a SCIM user"
Если вы обращаетесь к GitHub в GHE.com, замените api.github.com
выделенный поддомен api.SUBDOMAIN.ghe.com
предприятия.
Пример запроса
curl -L \
-X PATCH \
-H "Accept: application/scim+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
https://api.github.com/scim/v2/organizations/ORG/Users/SCIM_USER_ID \
-d '{"Operations":[{"op":"replace","value":{"displayName":"Octocat"}}]}'
Response
Status: 200
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"id": "edefdfedf-050c-11e7-8d32",
"externalId": "a7d0f98382",
"userName": "mona.octocat@okta.example.com",
"displayName": "Monalisa Octocat",
"name": {
"givenName": "Monalisa",
"familyName": "Octocat",
"formatted": "Monalisa Octocat"
},
"emails": [
{
"value": "mona.octocat@okta.example.com",
"primary": true
},
{
"value": "monalisa@octocat.github.com"
}
],
"active": true,
"meta": {
"resourceType": "User",
"created": "2017-03-09T16:11:13-05:00",
"lastModified": "2017-03-09T16:11:13-05:00",
"location": "https://api.github.com/scim/v2/organizations/octo-org/Users/edefdfedf-050c-11e7-8d32"
}
}
Delete a SCIM user from an organization
Deletes a SCIM user from an organization.
Подробные маркеры доступа для "Delete a SCIM user from an organization
Эта конечная точка работает со следующими точными типами маркеров:
- Маркеры доступа пользователей приложения GitHub
- Маркеры доступа к установке приложений GitHub
- Точные личные маркеры доступа
Маркер с точной детализацией должен иметь следующий набор разрешений.:
- "Members" organization permissions (write)
Параметры для "Delete a SCIM user from an organization"
Имя., Тип, Description |
---|
accept string Setting to |
Имя., Тип, Description |
---|
org string Обязательное полеThe organization name. The name is not case sensitive. |
scim_user_id string Обязательное полеThe unique identifier of the SCIM user. |
Коды состояния http-ответа для "Delete a SCIM user from an organization"
Код состояния | Описание |
---|---|
204 | No Content |
304 | Not modified |
403 | Forbidden |
404 | Resource not found |
Примеры кода для "Delete a SCIM user from an organization"
Если вы обращаетесь к GitHub в GHE.com, замените api.github.com
выделенный поддомен api.SUBDOMAIN.ghe.com
предприятия.
Пример запроса
curl -L \
-X DELETE \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
https://api.github.com/scim/v2/organizations/ORG/Users/SCIM_USER_ID
Response
Status: 204