Skip to content

Latest commit

 

History

History
166 lines (110 loc) · 9.65 KB

scim.md

File metadata and controls

166 lines (110 loc) · 9.65 KB
Raw
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 %}

Notes:

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

{% endnote %} {% 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 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".

{% 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 the beta of 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.product_name %} 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.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. 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.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.product_name %}. In the future, this documentation will display the correct URLs for {% data variables.product.product_name %}.

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 %}{% 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 %} {% note %}

Note: If the {% data variables.product.product_name %} uses Entra ID 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).

{% endif %}