54 lines
3.1 KiB
Markdown
54 lines
3.1 KiB
Markdown
---
|
|
title: SCIM
|
|
intro: 'You can control and manage your {% data variables.product.product_name %} organization members access using SCIM API.'
|
|
redirect_from:
|
|
- /v3/scim
|
|
versions:
|
|
fpt: '*'
|
|
topics:
|
|
- API
|
|
miniTocMaxHeadingLevel: 3
|
|
---
|
|
|
|
### SCIM Provisioning for Organizations
|
|
|
|
The SCIM API is used by SCIM-enabled Identity Providers (IdPs) to automate provisioning of {% data variables.product.product_name %} organization membership. The {% data variables.product.product_name %} API is based on version 2.0 of the [SCIM standard](http://www.simplecloud.info/). The {% data variables.product.product_name %} SCIM endpoint that an IdP should use is: `{% data variables.product.api_url_code %}/scim/v2/organizations/{org}/`.
|
|
|
|
{% note %}
|
|
|
|
**Note:** The SCIM API is available only to organizations on [{% data variables.product.prodname_ghe_cloud %}](/billing/managing-billing-for-your-github-account/about-billing-for-github-accounts) with [SAML SSO](/rest/overview/other-authentication-methods#authenticating-for-saml-sso) enabled. {% data reusables.scim.enterprise-account-scim %} For more information about SCIM, see "[About SCIM](/organizations/managing-saml-single-sign-on-for-your-organization/about-scim)."
|
|
|
|
{% endnote %}
|
|
|
|
### Authenticating calls to the SCIM API
|
|
|
|
You must authenticate as an owner of a {% data variables.product.product_name %} organization to use its SCIM API. The API expects an [OAuth 2.0 Bearer](/developers/apps/authenticating-with-github-apps) token to be included in the `Authorization` header. You may also use a personal access token, but you must first [authorize it for use with your SAML SSO organization](/github/authenticating-to-github/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on).
|
|
|
|
### Mapping of SAML and SCIM data
|
|
|
|
The SAML IdP and the SCIM client must use matching `NameID` and `userName` values for each user. This allows a user authenticating through SAML to be linked to their provisioned SCIM identity.
|
|
|
|
### Supported SCIM User attributes
|
|
|
|
Name | Type | Description
|
|
-----|------|--------------
|
|
`userName`|`string` | The username for the user.
|
|
`name.givenName`|`string` | The first name of the user.
|
|
`name.lastName`|`string` | The last name of the user.
|
|
`emails` | `array` | List of user emails.
|
|
`externalId` | `string` | This identifier is generated by the SAML provider, and is used as a unique ID by the SAML provider to match against a GitHub user. You can find the `externalID` for a user either at the SAML provider, or using the [List SCIM provisioned identities](#list-scim-provisioned-identities) endpoint and filtering on other known attributes, such as a user's GitHub username or email address.
|
|
`id` | `string` | Identifier generated by the GitHub SCIM endpoint.
|
|
`active` | `boolean` | Used to indicate whether the identity is active (true) or should be deprovisioned (false).
|
|
|
|
{% note %}
|
|
|
|
**Note:** Endpoint URLs for the SCIM API are case sensitive. For example, the first letter in the `Users` endpoint must be capitalized:
|
|
|
|
```shell
|
|
GET /scim/v2/organizations/{org}/Users/{scim_user_id}
|
|
```
|
|
|
|
{% endnote %}
|
|
|
|
{% include rest_operations_at_current_path %}
|