Skip to main content
REST API теперь версия. Дополнительные сведения см. в разделе "О управлении версиями API".

Конечные точки 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/objectidentifierexternalId

Другие поставщики удостоверений для SAML

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

Атрибут SAMLСопоставление атрибута SCIM
NameIDuserName

Существует два разных способа: учетная запись пользователя GitHub может связаться с удостоверением SCIM в организации при совпадении этих атрибутов SAML/SCIM:

  1. Для пользователей, которые еще не являются членами организации:

    • IdP отправляет вызов подготовки SCIM к GitHub для пользователя, который не является членом организации. Это создает приглашение организации и удостоверение SCIM без связи в организации.
    • Пользователь проходит проверку подлинности через SAML в организации.
    • GitHub автоматически связывает удостоверение SAML и SCIM с новой учетной записью пользователя в организации.
  2. Для существующих членов организации:

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

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

Поддерживаемые атрибуты пользователя SCIM

Имя.ТипОписание
userNamestringИмя пользователя.
name.givenNamestringИмя пользователя.
name.familyNamestringФамилия пользователя.
emailsarrayСписок адресов электронной почты пользователя.
externalIdstringЭтот идентификатор создается поставщиком SAML и используется этим поставщиком в качестве уникального идентификатора для сопоставления с пользователем GitHub. externalID для пользователя можно найти в поставщике SAML. Или используйте конечную точку Список подготовленных удостоверений SCIM и выполните фильтрацию по другим известным атрибутам, таким как имя пользователя или адрес электронной почты пользователя GitHub.
idstringИдентификатор, созданный конечной точкой SCIM GitHub.
activebooleanУказывает, является ли удостоверение активным (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

Эта конечная точка работает со следующими точными типами маркеров:

Маркер с точной детализацией должен иметь следующий набор разрешений.:

  • "Members" organization permissions (read)

Параметры для "List SCIM provisioned identities"

Заголовки
Имя., Тип, Description
accept string

Setting to application/vnd.github+json is recommended.

Параметры пути
Имя., Тип, 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 (eq). You can filter results that are equal to id, userName, emails, and externalId. For example, to search for an identity with the userName Octocat, you would use this query:

?filter=userName%20eq%20\"Octocat\".

To filter results for the identity with the email octocat@github.com, you would use this query:

?filter=emails%20eq%20\"octocat@github.com\".

Коды состояния 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предприятия.

Примеры запросов

get/scim/v2/organizations/{org}/Users
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

Эта конечная точка работает со следующими точными типами маркеров:

Маркер с точной детализацией должен иметь следующий набор разрешений.:

  • "Members" organization permissions (write)

Параметры для "Provision and invite a SCIM user"

Заголовки
Имя., Тип, Description
accept string

Setting to application/vnd.github+json is recommended.

Параметры пути
Имя., Тип, 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 Обязательное поле
Имя., Тип, Description
givenName string Обязательное поле
familyName string Обязательное поле
formatted string
emails array of objects Обязательное поле

user 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предприятия.

Пример запроса

post/scim/v2/organizations/{org}/Users
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

Эта конечная точка работает со следующими точными типами маркеров:

Маркер с точной детализацией должен иметь следующий набор разрешений.:

  • "Members" organization permissions (read)

Параметры для "Get SCIM provisioning information for a user"

Заголовки
Имя., Тип, Description
accept string

Setting to application/vnd.github+json is recommended.

Параметры пути
Имя., Тип, 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предприятия.

Пример запроса

get/scim/v2/organizations/{org}/Users/{scim_user_id}
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

Эта конечная точка работает со следующими точными типами маркеров:

Маркер с точной детализацией должен иметь следующий набор разрешений.:

  • "Members" organization permissions (write)

Параметры для "Update a provisioned organization membership"

Заголовки
Имя., Тип, Description
accept string

Setting to application/vnd.github+json is recommended.

Параметры пути
Имя., Тип, 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 Обязательное поле
Имя., Тип, Description
givenName string Обязательное поле
familyName string Обязательное поле
formatted string
emails array of objects Обязательное поле

user 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предприятия.

Пример запроса

put/scim/v2/organizations/{org}/Users/{scim_user_id}
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

Эта конечная точка работает со следующими точными типами маркеров:

Маркер с точной детализацией должен иметь следующий набор разрешений.:

  • "Members" organization permissions (write)

Параметры для "Update an attribute for a SCIM user"

Заголовки
Имя., Тип, Description
accept string

Setting to application/vnd.github+json is recommended.

Параметры пути
Имя., Тип, 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

Имя., Тип, Description
op string Обязательное поле

Возможные значения: add, remove, replace

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предприятия.

Пример запроса

patch/scim/v2/organizations/{org}/Users/{scim_user_id}
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

Эта конечная точка работает со следующими точными типами маркеров:

Маркер с точной детализацией должен иметь следующий набор разрешений.:

  • "Members" organization permissions (write)

Параметры для "Delete a SCIM user from an organization"

Заголовки
Имя., Тип, Description
accept string

Setting to application/vnd.github+json is recommended.

Параметры пути
Имя., Тип, 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предприятия.

Пример запроса

delete/scim/v2/organizations/{org}/Users/{scim_user_id}
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