# SCIM 的 REST API 端点

使用 REST API 通过 SCIM 控制和管理GitHub组织成员的访问权限。

> \[!NOTE]
> 此操作允许你使用 SCIM 在GitHub Enterprise Cloud上预配对组织的访问。 此操作不适用于Enterprise Managed Users。 有关使用 SCIM 预配 托管用户帐户 的详细信息，请参阅 [SCIM 的 REST API 端点](/zh/enterprise-cloud@latest/rest/enterprise-admin/scim)。

## 关于 SCIM

### 组织的 SCIM 预配

已启用 SCIM 的标识提供者（IdP）使用这些终结点自动预配 GitHub 组织成员身份，并且基于 [SCIM 标准](http://www.simplecloud.info/)版本 2.0。 身份提供者应使用 `https://api.github.com/scim/v2/organizations/{org}/` 作为 SCIM 终结点的基础 URL GitHub。

> \[!NOTE]
>
> * 这些终结点仅适用于启用了 SAML SSO 且使用 GitHub Enterprise Cloud 的单个组织。 有关 SCIM 的详细信息，请参阅 [关于组织的 SCIM](/zh/enterprise-cloud@latest/organizations/managing-saml-single-sign-on-for-your-organization/about-scim-for-organizations)。 有关为 SAML SSO 组织授权令牌的详细信息，请参阅 [对 REST API 进行身份验证](/zh/enterprise-cloud@latest/rest/overview/authenticating-to-the-rest-api)。
> * 这些终结点不能用于企业帐户或与具有托管用户的组织一起使用。

### 身份验证

你必须验证 GitHub 组织所有者的身份才能使用这些终结点。 REST API 要求在标头中包含 GitHub App OAuth 2.0 持有者令牌（例如`Authorization`，用户访问令牌）。 如果使用 personal access token (classic) 进行身份验证，它必须具备 `admin:org` 权限范围，并且您还必须 [授权其用于您的 SAML SSO 组织](/zh/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on)。

### 匹配 SAML 和 SCIM 属性

若要成功将 GitHub 用户帐户链接到组织中的 SCIM 标识，标识提供者的 SAML 响应和 SCIM API 预配调用中的特定属性必须与用户匹配。

#### Microsoft Entra ID 用于 SAML

将 Entra ID（以前称为 Azure AD）用于 SAML 时，以下 SAML 属性和 SCIM 属性必须匹配。

| SAML 属性                                                         | 匹配的 SCIM 属性  |
| :-------------------------------------------------------------- | :----------- |
| `http://schemas.microsoft.com/identity/claims/objectidentifier` | `externalId` |

#### 用于 SAML 的其他 IDP

要将其他 IdP 用于 SAML，以下 SAML 声明和 SCIM 属性必须匹配。

| SAML 属性  | 匹配的 SCIM 属性 |
| :------- | :---------- |
| `NameID` | `userName`  |

当这些 SAML/SCIM 属性匹配时， GitHub 用户帐户可以通过两种不同的方式链接到组织中的 SCIM 标识：

1. 对于还不是组织成员的用户：
   * IdP 为 GitHub 不是组织成员的用户发送 SCIM 预配调用。 这会在组织中生成一个组织邀请和一个未链接的 SCIM 标识。
   * 用户通过组织中的 SAML 进行身份验证。
   * GitHub 自动将 SAML 和 SCIM 标识链接到组织中的新用户帐户。

2. 对于现有组织成员：
   * IdP 向 GitHub 已是组织成员的用户发送 SCIM 预配调用。
   * 如果组织成员在组织中没有链接的 SAML 标识，这会在组织中生成组织邀请和未链接的 SCIM 标识。 用户通过组织中的 SAML 进行身份验证，以链接其 SAML 和 SCIM 标识。
   * 如果组织成员在组织中已具有链接的 SAML 标识，GitHub 会自动将 SCIM 标识链接到组织中的现有用户帐户。 而不会创建组织邀请。

确保用户在组织中正确链接到其 SCIM 标识有助于防止在 IdP 端删除用户对应用的访问权限时出现有关 SCIM 取消预配的意外问题。 有关审核组织中链接的 SCIM 标识的详细信息，请参阅 [排除组织的标识和访问管理故障](/zh/enterprise-cloud@latest/organizations/managing-saml-single-sign-on-for-your-organization/troubleshooting-identity-and-access-management-for-your-organization#auditing-organization-members-on-github)

### 支持的 SCIM 用户属性

| 名称                | 类型        | 说明                                                                                                                                                                                   |
| ----------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `userName`        | `string`  | 用户的用户名。                                                                                                                                                                              |
| `name.givenName`  | `string`  | 用户的名字。                                                                                                                                                                               |
| `name.familyName` | `string`  | 用户的姓氏。                                                                                                                                                                               |
| `emails`          | `array`   | 用户电子邮件列表。                                                                                                                                                                            |
| `externalId`      | `string`  | 此标识符由 SAML 提供程序生成，并用作 SAML 提供程序的唯一 ID，以与GitHub用户匹配。 可以在 SAML 提供程序中找到用户的 `externalID`，或者也可以使用 [列出 SCIM 预配标识](#list-scim-provisioned-identities) 终结点，筛选其他已知属性，例如用户的 GitHub 用户名或电子邮件地址。 |
| `id`              | `string`  | GitHub SCIM 终结点生成的标识符。                                                                                                                                                               |
| `active`          | `boolean` | 用于表示身份是处于活动状态 (true) 还是应解除预配 (false)。                                                                                                                                                |

> \[!NOTE]
> 这些终结点区分大小写。 例如，`Users` 终结点中的第一个字母必须大写：
>
> ```shell
> GET /scim/v2/organizations/{org}/Users/{scim_user_id}
> ```

> \[!NOTE]
> Most endpoints use `Authorization: Bearer <YOUR-TOKEN>` and `Accept: application/vnd.github+json` headers, plus `X-GitHub-Api-Version: 2022-11-28`. Curl examples below omit these standard headers for brevity.

## List SCIM provisioned identities

```
GET /scim/v2/organizations/{org}/Users
```

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.

### Parameters

#### Headers

* **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

* **`org`** (string) (required)
  The organization name. The name is not case sensitive.

* **`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 response status codes

* **200** - OK

* **304** - Not modified

* **400** - Bad request

* **403** - Forbidden

* **404** - Resource not found

* **429** - Too many requests

### Code examples

#### Example 1: Status Code 200

**Request:**

```curl
curl -L \
  -X GET \
  https://api.github.com/scim/v2/organizations/ORG/Users
```

**Response schema (Status: 200):**

* `schemas`: required, array of string
* `totalResults`: required, integer
* `itemsPerPage`: required, integer
* `startIndex`: required, integer
* `Resources`: required, array of `SCIM /Users`:
  * `schemas`: required, array of string
  * `id`: required, string
  * `externalId`: string or null
  * `userName`: string or null
  * `displayName`: string or null
  * `name`: object:
    * `givenName`: string or null
    * `familyName`: string or null
    * `formatted`: string or null
  * `emails`: required, array of objects:
    * `value`: required, string
    * `primary`: boolean
    * `type`: string
  * `active`: required, boolean
  * `meta`: required, object:
    * `resourceType`: string
    * `created`: string, format: date-time
    * `lastModified`: string, format: date-time
    * `location`: string, format: uri
  * `organization_id`: integer
  * `operations`: array of objects:
    * `op`: required, string, enum: `add`, `remove`, `replace`
    * `path`: string
    * `value`: one of:
      * **string**
      * **object**
      * **array**
  * `groups`: array of objects:
    * `value`: string
    * `display`: string
  * `roles`: array of objects:
    * `value`: string
    * `primary`: boolean
    * `type`: string
    * `display`: string

#### Example 2: Status Code 200

**Request:**

```curl
curl -L \
  -X GET \
  https://api.github.com/scim/v2/organizations/ORG/Users
```

**Response schema (Status: 200):**

* `schemas`: required, array of string
* `totalResults`: required, integer
* `itemsPerPage`: required, integer
* `startIndex`: required, integer
* `Resources`: required, array of `SCIM /Users`:
  * `schemas`: required, array of string
  * `id`: required, string
  * `externalId`: string or null
  * `userName`: string or null
  * `displayName`: string or null
  * `name`: object:
    * `givenName`: string or null
    * `familyName`: string or null
    * `formatted`: string or null
  * `emails`: required, array of objects:
    * `value`: required, string
    * `primary`: boolean
    * `type`: string
  * `active`: required, boolean
  * `meta`: required, object:
    * `resourceType`: string
    * `created`: string, format: date-time
    * `lastModified`: string, format: date-time
    * `location`: string, format: uri
  * `organization_id`: integer
  * `operations`: array of objects:
    * `op`: required, string, enum: `add`, `remove`, `replace`
    * `path`: string
    * `value`: one of:
      * **string**
      * **object**
      * **array**
  * `groups`: array of objects:
    * `value`: string
    * `display`: string
  * `roles`: array of objects:
    * `value`: string
    * `primary`: boolean
    * `type`: string
    * `display`: string

## Provision and invite a SCIM user

```
POST /scim/v2/organizations/{org}/Users
```

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."

### Parameters

#### Headers

* **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

* **`org`** (string) (required)
  The organization name. The name is not case sensitive.

#### Body parameters

* **`userName`** (string) (required)
  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) (required)
  * **`givenName`** (string) (required)
  * **`familyName`** (string) (required)
  * **`formatted`** (string)

* **`emails`** (array of objects) (required)
  user emails
  * **`value`** (string) (required)
  * **`primary`** (boolean)
  * **`type`** (string)

* **`schemas`** (array of strings)

* **`externalId`** (string)

* **`groups`** (array of strings)

* **`active`** (boolean)

### HTTP response status codes

* **201** - Created

* **304** - Not modified

* **400** - Bad request

* **403** - Forbidden

* **404** - Resource not found

* **409** - Conflict

* **500** - Internal server error

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X POST \
  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 schema (Status: 201):**

* `schemas`: required, array of string
* `id`: required, string
* `externalId`: string or null
* `userName`: string or null
* `displayName`: string or null
* `name`: object:
  * `givenName`: string or null
  * `familyName`: string or null
  * `formatted`: string or null
* `emails`: required, array of objects:
  * `value`: required, string
  * `primary`: boolean
  * `type`: string
* `active`: required, boolean
* `meta`: required, object:
  * `resourceType`: string
  * `created`: string, format: date-time
  * `lastModified`: string, format: date-time
  * `location`: string, format: uri
* `organization_id`: integer
* `operations`: array of objects:
  * `op`: required, string, enum: `add`, `remove`, `replace`
  * `path`: string
  * `value`: one of:
    * **string**
    * **object**
    * **array**
* `groups`: array of objects:
  * `value`: string
  * `display`: string
* `roles`: array of objects:
  * `value`: string
  * `primary`: boolean
  * `type`: string
  * `display`: string

## Get SCIM provisioning information for a user

```
GET /scim/v2/organizations/{org}/Users/{scim_user_id}
```

Gets SCIM provisioning information for a user.

### Parameters

#### Headers

* **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

* **`org`** (string) (required)
  The organization name. The name is not case sensitive.

* **`scim_user_id`** (string) (required)
  The unique identifier of the SCIM user.

### HTTP response status codes

* **200** - OK

* **304** - Not modified

* **403** - Forbidden

* **404** - Resource not found

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X GET \
  https://api.github.com/scim/v2/organizations/ORG/Users/SCIM_USER_ID
```

**Response schema (Status: 200):**

Same response schema as [Provision and invite a SCIM user](#provision-and-invite-a-scim-user).

## Update a provisioned organization membership

```
PUT /scim/v2/organizations/{org}/Users/{scim_user_id}
```

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}.

### Parameters

#### Headers

* **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

* **`org`** (string) (required)
  The organization name. The name is not case sensitive.

* **`scim_user_id`** (string) (required)
  The unique identifier of the SCIM user.

#### Body parameters

* **`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) (required)
  Configured by the admin. Could be an email, login, or username

* **`name`** (object) (required)
  * **`givenName`** (string) (required)
  * **`familyName`** (string) (required)
  * **`formatted`** (string)

* **`emails`** (array of objects) (required)
  user emails
  * **`type`** (string)
  * **`value`** (string) (required)
  * **`primary`** (boolean)

### HTTP response status codes

* **200** - OK

* **304** - Not modified

* **403** - Forbidden

* **404** - Resource not found

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X PUT \
  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 schema (Status: 200):**

Same response schema as [Provision and invite a SCIM user](#provision-and-invite-a-scim-user).

## Update an attribute for a SCIM user

```
PATCH /scim/v2/organizations/{org}/Users/{scim_user_id}
```

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
}
}]
}

### Parameters

#### Headers

* **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

* **`org`** (string) (required)
  The organization name. The name is not case sensitive.

* **`scim_user_id`** (string) (required)
  The unique identifier of the SCIM user.

#### Body parameters

* **`schemas`** (array of strings)

* **`Operations`** (array of objects) (required)
  Set of operations to be performed
  * **`op`** (string) (required)
    Can be one of: `add`, `remove`, `replace`
  * **`path`** (string)
  * **`value`** (object or array or string)

### HTTP response status codes

* **200** - OK

* **304** - Not modified

* **400** - Bad request

* **403** - Forbidden

* **404** - Resource not found

* **429** - Too Many Requests

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X PATCH \
  https://api.github.com/scim/v2/organizations/ORG/Users/SCIM_USER_ID \
  -d '{
  "Operations": [
    {
      "op": "replace",
      "value": {
        "displayName": "Octocat"
      }
    }
  ]
}'
```

**Response schema (Status: 200):**

Same response schema as [Provision and invite a SCIM user](#provision-and-invite-a-scim-user).

## Delete a SCIM user from an organization

```
DELETE /scim/v2/organizations/{org}/Users/{scim_user_id}
```

Deletes a SCIM user from an organization.

### Parameters

#### Headers

* **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

* **`org`** (string) (required)
  The organization name. The name is not case sensitive.

* **`scim_user_id`** (string) (required)
  The unique identifier of the SCIM user.

### HTTP response status codes

* **204** - No Content

* **304** - Not modified

* **403** - Forbidden

* **404** - Resource not found

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X DELETE \
  https://api.github.com/scim/v2/organizations/ORG/Users/SCIM_USER_ID
```

**Response schema (Status: 204):**