Provisioning users with SCIM using the REST API

About provisioning for Enterprise Managed Users

To create, manage, and deactivate user accounts for your enterprise members on GitHub.com, your IdP must implement SCIM for communication with GitHub. SCIM is an open specification for management of user identities between systems. Different IdPs provide different experiences for the configuration of SCIM provisioning. For more information about provisioning on GitHub Enterprise Cloud, see "Configuring SCIM provisioning for Enterprise Managed Users."

GitHub partners with some developers of identity management systems to provide a "paved-path" integration with Enterprise Managed Users. If your company does not use a partner IdP, you can configure provisioning from an identity system that communicates with GitHub's REST API. This guide will help you understand the following topics related to GitHub's implementation.

• How to review and stream detailed audit logs for your enterprise
• The REST API, including endpoints for SCIM and usage expectations
• Troubleshooting

Alternatively, you can use a partner IdP for both authentication and provisioning. For more information, see "About Enterprise Managed Users."

GitHub has not tested every IdP. GitHub Support provides limited support for partner IdPs. You may be able to integrate an IdP that adheres to the SCIM specification and GitHub's guidelines, but for support with the IdP itself or building an integration, refer to the developer's documentation, support team, or other resources.

Prerequisites

• Before you configure provisioning, you must configure authentication. For more information, see "Configuring authentication for Enterprise Managed Users."

• Before you configure provisioning, ensure that you understand the integration requirements and level of support for your IdP. For more information, see "About Enterprise Managed Users."

• To integrate with GitHub's REST API, the IdP must support the System for Cross-domain Identity Management (SCIM) 2.0 standard. For more information, see the following RFCs on the IETF website.

  • RFC 7642: Definitions, Overview, Concepts, and Requirements
  • RFC 7643: Core Schema
  • RFC 7644: Protocol

• GitHub recommends that you only authenticate requests to the REST API endpoints for SCIM using a personal access token (classic) associated with your enterprise's setup user. The token requires the admin:enterprise scope. For more information, see "Configuring SCIM provisioning for Enterprise Managed Users"

• The user records for the systems that you use for authentication and provisioning must share a unique identifier and satisfy GitHub's matching criteria. For more information, see "SCIM" in the REST API documentation.

• After you initially configure authentication and provisioning, GitHub does not recommend migration to a different platform for authentication or provisioning. If you need to migrate an existing enterprise to a different platform for authentication or provisioning, contact your account manager on GitHub's Sales team.

Configuring audit log streaming

The audit log for your enterprise displays details about activity in your enterprise. You can use the audit log to support your configuration of SCIM. For more information, see "About the audit log for your enterprise."

Due to the volume of events in this log, GitHub retains the data for six months. To ensure that you don't lose audit log data, and to view more granular activity in the audit log, GitHub recommends that you configure audit log streaming. When you stream the audit log, you can optionally choose to stream events for API requests, including requests to endpoints for SCIM provisioning. For more information, see "Streaming the audit log for your enterprise."

Understanding the REST API for SCIM

To make SCIM calls and manage users, you'll use GitHub's REST API. For more information about accessing resources in the REST API, see "Resources in the REST API."

• REST API endpoints for SCIM
• About rate limits
• User and group attributes
• About mapping of external identities
• Ensuring users have the access you intend
• About suspension and reprovisioning of users

REST API endpoints for SCIM

The following tables describe the SCIM endpoints offered by the REST API. You can read more information in the REST API documentation. The documentation includes code samples, required headers and path parameters, and HTTP response codes.

For more information about authentication of requests to these endpoints, see "SCIM" in the REST API documentation.

Requests that don't match the REST API's expectations will return a 400 Bad Request error.

• REST API endpoints for user management
• REST API endpoints for group management

REST API endpoints for user management

To provision users, make requests to the following REST API endpoints.

Action	Method	Endpoint and more information
Create a user	POST	Provision a SCIM enterprise user
Retrieve a user	GET	Get SCIM provisioning information for an enterprise user
Update all of a user's attributes	PUT	Set SCIM information for a provisioned enterprise user
Update an individual user attribute	PATCH	Update an attribute for a SCIM enterprise user
List all users	GET	List SCIM provisioned identities for an enterprise
Delete a user	DELETE	Delete a SCIM user from an enterprise

REST API endpoints for group management

To control access to repositories in your enterprise, your SCIM integration can manage organization and team membership for users via groups on your IdP. For more information, see "Managing team memberships with identity provider groups."

To manage groups, make requests to the following REST API endpoints.

Action	Method	Endpoint and more information
Create a group	POST	Provision a SCIM enterprise group
Retrieve a group	GET	Get SCIM provisioning information for an enterprise group
Update all of a group's attributes	PUT	Set SCIM information for a provisioned enterprise group
Update an individual group attribute	PATCH	Update an attribute for a SCIM enterprise group
List all groups	GET	List provisioned SCIM groups for an enterprise
Delete a group	DELETE	Delete a SCIM group from an enterprise

About rate limits

To avoid exceeding the rate limit on GitHub Enterprise Cloud, do not assign more than 1,000 users per hour to the SCIM integration on your IdP. If you use groups to assign users to the IdP application, do not add more than 1,000 users to each group per hour. If you exceed these thresholds, attempts to provision users may fail with a "rate limit" error. You can review your IdP logs to confirm if attempted SCIM provisioning or push operations failed due to a rate limit error. The response to a failed provisioning attempt will depend on the IdP.

For more information, see "Rate limits for the REST API."

User and group attributes

Requests to the REST API support specific attributes for users and groups. For more information, see "Supported SCIM user attributes" and "Supported SCIM group attributes" in the REST API documentation for SCIM operations.

For example, you can use the roles attribute to assign a role in the enterprise to a user or group. If you grant multiple roles to a user, the role with more privileged access takes precedence.

Role	More information in "Roles in an enterprise"
enterprise_owner	"Enterprise owners"
billing_manager	"Billing managers"
user	"Enterprise members"
guest_collaborator	"Guest collaborators"

About mapping of external identities

After successful authentication, GitHub Enterprise Cloud links the user who authenticated to an identity provisioned by SCIM. The unique identifiers for authentication and provisioning must match. For more information, see "SCIM" in the REST API documentation.

You can view this mapping on GitHub.com. For more information, see "Viewing and managing a user's SAML access to your enterprise."

Ensuring users have the access you intend

If your integration manages access using groups on your IdP, you can validate that users get the access you intend. You can use the REST API to compare your IdP's group memberships with GitHub's understanding of those groups. For more information, see "External groups" and "Teams" in the REST API documentation.

About suspension and reprovisioning of users

You cannot completely delete a managed user account on GitHub.com. Instead, you can either temporarily or permanently suspend the account.

To temporarily suspend a user, sets the user record's active attribute to false using a PATCH or PUT request. After you temporarily suspend an account, the user can no longer sign in to access your enterprise on GitHub.com. For more information, see "Update an attribute for a SCIM enterprise user" or "Set SCIM information for a provisioned enterprise user" in the REST API documentation for SCIM operations.

To permanently suspend a user, send a DELETE request. If you permanently suspend an account, you cannot reactivate the account. For more information, see "Delete a SCIM user from an enterprise" in the REST API documentation for SCIM operations.

To reprovision a user, set the user record's active attribute to true using a POST, PUT, or PATCH request. If you permanently suspended the account, a subsequent provisioning event will create a new account for the person who's signing in. The newly provisioned account will have no relationship to the original account. For more information, see "Provision a SCIM enterprise user", "Set SCIM information for a provisioned enterprise user," or "Update an attribute for a SCIM enterprise user" in the REST API documentation for SCIM operations.

Troubleshooting

• If GitHub is rate-limiting your requests to the REST API, you can learn more in "About rate limits."

• If you enable audit log streaming and stream events for API requests, you can review any requests to the REST API endpoints for SCIM by filtering for events from the EnterpriseUsersScim or EnterpriseGroupsScim controllers.

• If your integration manages access using groups on your IdP, you can review external_group category events in your enterprise's audit log to confirm the success of SCIM calls. You can also view troubleshooting information in the web interface for GitHub. For more information, see "Audit log events for your enterprise" and "Troubleshooting team membership with identity provider groups."

Further reading

• "Username considerations for external authentication"