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

title, intro, versions, topics, miniTocMaxHeadingLevel

title	intro	versions	topics	miniTocMaxHeadingLevel
SCIM	You can automate user creation and team memberships using the SCIM API.	ghes >=3.6	API	3

{% note %}

Note: The SCIM API for {% data variables.product.product_name %} is currently in private beta and subject to change. To access the private beta and test the API, contact your account manager on {% data variables.contact.contact_enterprise_sales %}.

{% endnote %}

About the SCIM API

{% data variables.product.product_name %} provides a SCIM API for use by SCIM-enabled Identity Providers (IdPs). An integration on the IdP can use the 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 "About SAML for enterprise IAM."

The SCIM API is based on SCIM 2.0. For more information, see the specification.

SCIM endpoint URLs

An IdP can use the following root URL to communicate with the SCIM API for a {% data variables.product.product_name %} instance.

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

Endpoint URLs for the SCIM API are case-sensitive. For example, the first letter in the Users endpoint must be capitalized.

GET /scim/v2/Users/{scim_user_id}

Authenticating calls to the SCIM API

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 "Roles in an enterprise."

To authenticate requests to the API, the person who configures SCIM on the IdP must use a personal access token (classic) with admin:enterprise scope, which the IdP must provide in the request's Authorization header. For more information about personal access tokens (classic), see "Creating a personal access token".

{% note %}

Note: Enterprise owners must generate and use a personal access token (classic) for authentication of requests to the SCIM API. {% ifversion ghes > 3.8 %}Fine-grained personal access tokens and {% endif %}GitHub app callers are not supported at this time.

{% endnote %}

About 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

The SCIM API's User endpoints 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).