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

title, shortTitle, allowTitleToDifferFromFilename, intro, versions, topics, autogenerated

title	shortTitle	allowTitleToDifferFromFilename	intro	versions	topics	autogenerated
REST API endpoints for SCIM	SCIM	true	Use the REST API to automate user creation and team memberships with SCIM.	ghec ghes * *	API	rest

{% ifversion emu-public-scim-schema %}

Note

• {% data reusables.scim.ghec-open-scim-operation-differentiation %}
• {% data reusables.scim.ghec-open-scim-test-in-isolation %}

{% endif %}

About SCIM

{% ifversion ghec %}

{% data reusables.enterprise_user_management.about-scim-provisioning %} If you don't use a partner IdP with an existing integration, you can integrate using the following API endpoints. For more information, see AUTOTITLE.

Base URL

To manage your enterprise's users and groups using SCIM, use the following base URL to communicate with the endpoints in this category.

{% data variables.product.rest_url %}/scim/v2/enterprises/{enterprise}/

Authentication

To authenticate API requests, the person who configures SCIM on the IdP must use a {% data variables.product.pat_v1 %} with scim: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.

{% data variables.product.company_short %} recommends authenticating as the setup user for the enterprise. Other user accounts are created through SCIM, so authenticating as a different user could result in unintended consequences, such as getting locked out of your enterprise. Write requests to these APIs are possible through our published IdP applications, or through direct API access to our SCIM endpoints. If another enterprise owner needs to read information from the API, use a {% data variables.product.pat_v1 %} with the admin:enterprise scope to make GET requests on your current SCIM implementation. For more information, see AUTOTITLE.

Mapping of SAML and SCIM data

After a {% data variables.enterprise.prodname_managed_user %} successfully authenticates to access your enterprise using SAML SSO, {% data variables.product.github %} links the user to a SCIM provisioned identity. To link the identities successfully, the SAML identity provider and the SCIM integration must use matching unique identifiers.

{% data variables.product.company_short %} requires the following SAML claim and SCIM attribute to successfully match the user with the identity provisioned by SCIM. Identity providers may differ in the field used to uniquely identify a user.

Microsoft Entra ID for SAML

To use Entra ID (previously known as Azure AD) for SAML, the following SAML claims and SCIM attribute must match.

SAML claim	Matching SCIM attribute
http://schemas.microsoft.com/identity/claims/objectidentifier	externalId

Other IdPs for SAML

To use other IdPs for SAML, the following SAML claims and SCIM attribute must match.

SAML claim	Matching SCIM attribute
NameID	userName

Supported SCIM user attributes

Users 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 SCIM provider. Undergoes normalization before being used. Must be unique per user.
emails	Array	List of the user's emails.
roles	Array	List of the user's roles.
externalId	String	This identifier is generated by a SCIM provider. Must be unique per user.
id	String	Identifier generated by the GitHub's SCIM endpoint.
active	Boolean	Indicates whether the identity is active (true) or should be suspended (false).

Supported SCIM group attributes

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

Name	Type	Description
displayName	String	Human-readable name for a group.
members	String	List of members who are assigned to the group in SCIM provider
externalId	String	This identifier is generated by a SCIM provider. Must be unique per user.

{% endif %}

{% ifversion ghes %}

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

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

{% data variables.product.github %} 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.prodname_ghe_server %} instance that uses SAML single sign-on (SSO) for authentication. 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.prodname_ghe_server %} instance.

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

Do not include the enterprises/{enterprise}/ portion of the URLs provided in the endpoint documentation below. This part of the path is not applicable to {% data variables.product.prodname_ghe_server %}. In the future, this documentation will display the correct URLs for {% data variables.product.prodname_ghe_server %}.

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.prodname_ghe_server %} 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 the {% ifversion scim-enterprise-scope %}scim:enterprise{% else %}admin:enterprise{% endif %} 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

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

Mapping of SAML and SCIM data

After a {% data variables.product.prodname_ghe_server %} user successfully authenticates using SAML SSO, {% data variables.product.github %} links the user to a SCIM provisioned identity. To link the identities successfully, the SAML identity provider and the SCIM integration must use matching unique identifiers.

When a mismatch between a user's SAML and SCIM data occurs, {% data variables.product.company_short %} will return an error stating which attributes from SAML and SCIM did not match. For more information on this error, see AUTOTITLE.

{% data variables.product.company_short %} requires the following SAML claim and SCIM attribute to successfully match the user with the identity provisioned by SCIM. Identity providers may differ in the field used to uniquely identify a user.

Microsoft Entra ID for SAML

To use Entra ID (previously known as Azure AD) for SAML, the following SAML claims and SCIM attribute must match.

SAML claim	Matching SCIM attribute
http://schemas.microsoft.com/identity/claims/objectidentifier	externalId

Other IdPs for SAML

To use other IdPs for SAML, {% data variables.product.company_short %} will use the "Username" attribute configured in your SAML "User attributes" to match against the SCIM attribute listed below. If left blank, the "Username" attribute in your SAML "User attributes" will default to the SAML NameID. For more information about SAML configurations, see AUTOTITLE.

SAML claim	Matching SCIM attribute
"Username" attribute configured in your SAML "User attributes", or NameID if left blank	userName

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.prodname_ghe_server %} 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).

{% endif %}