Конечные точки REST API для 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

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

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

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

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

Select the example type

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 Обязательное поле

Properties of name

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

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

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 Обязательное поле

Properties of name

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

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

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

Properties of Operations

Имя., Тип, 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