docs/content/rest/enterprise-admin/scim.md

title, intro, versions, topics, autogenerated

title	intro	versions	topics	autogenerated
SCIM	Use the REST API to automate user creation and team memberships with SCIM.	ghes *	API	rest

About SCIM

{% data reusables.scim.ghes-beta-note %}

{% data reusables.user-settings.enterprise-admin-api-classic-pat-only %}

{% data variables.product.product_name %} provides endpoints for use by SCIM-enabled Identity Providers (IdPs). An integration on the IdP can use the REST API to automatically provision, manage, or deprovision user accounts on a {% data variables.product.product_name %} instance that uses SAML single sign-on (SSO) for authentication. For more information about SAML SSO, see "AUTOTITLE."

These endpoints are based on SCIM 2.0. For more information, refer to your IdP's documentation or see the specification on the IETF website.

Root URLs

An IdP can use the following root URL to communicate with the endpoints in this category for a {% data variables.product.product_name %} instance.

{% data variables.product.api_url_code %}/scim/v2/

Endpoints in this category are case-sensitive. For example, the first letter in the Users endpoint must be capitalized.

GET /scim/v2/Users/{scim_user_id}

Authentication

The SCIM integration on the IdP performs actions on behalf of an enterprise owner for the {% data variables.product.product_name %} instance. For more information, see "AUTOTITLE."

To authenticate API requests, the person who configures SCIM on the IdP must use a {% data variables.product.pat_v1 %} with admin:enterprise scope, which the IdP must provide in the request's Authorization header. For more information about {% data variables.product.pat_v1_plural %}, see "AUTOTITLE".

{% note %}

Note: Enterprise owners must generate and use a {% data variables.product.pat_v1 %} for authentication of requests to endpoints in this category. {% ifversion ghes > 3.8 %}{% data variables.product.pat_v2_caps %} and {% endif %}GitHub app callers are not supported at this time.

{% endnote %}

Mapping of SAML and SCIM data

The {% data variables.product.product_name %} instance links each user who authenticates successfully with SAML SSO to a SCIM identity. To link the identities successfully, the SAML IdP and the SCIM integration must use matching SAML NameID and SCIM userName values for each user.

{% ifversion ghes > 3.7 %} {% note %}

Note: If the {% data variables.product.product_name %} uses Azure AD as a SAML IdP, {% data variables.product.product_name %} will also check the SCIM externalId claim and SAML http://schemas.microsoft.com/identity/claims/objectidentifier claim to match users first, instead of using NameID and userName.

{% endnote %} {% endif %}

Supported SCIM user attributes

User endpoints in this category support the following attributes within a request's parameters.

Name	Type	Description
displayName	String	Human-readable name for a user.
name.formatted	String	The user's full name, including all middle names, titles, and suffixes, formatted for display.
name.givenName	String	The first name of the user.
name.familyName	String	The last name of the user.
userName	String	The username for the user, generated by the IdP. Undergoes normalization before being used.
emails	Array	List of the user's emails.
roles	Array	List of the user's roles.
externalId	String	This identifier is generated by an IdP provider. You can find the externalId for a user either on the IdP, or by using the List SCIM provisioned identities endpoint and filtering on other known attributes, such as a user's username or email address on the {% data variables.product.product_name %} instance.
id	String	Identifier generated by the instance's SCIM endpoint.
active	Boolean	Indicates whether the identity is active (true) or should be suspended (false).