Note
SCIM for GitHub Enterprise Server is currently in beta and subject to change. GitHub recommends testing with a staging instance first. See Setting up a staging instance.
About provisioning with Okta
If you use Okta as an IdP, you can use Okta's application to provision user accounts, manage enterprise membership, and manage team memberships for organizations in your enterprise. Okta is a partner IdP, so you can simplify your authentication and provisioning configuration by using the Okta application to manage both SAML single-sign on and SCIM provisioning on GitHub Enterprise Server.
Alternatively, if you only intend to use Okta for SAML authentication and you want to use a different IdP for provisioning, you can integrate with GitHub's REST API for SCIM. For more information, see Provisioning users and groups with SCIM using the REST API.
Supported features
GitHub Enterprise Server supports the following provisioning features for Okta.
| Feature | Description |
|---|---|
| Push New Users | Users that are assigned to GitHub's application in Okta are automatically created in the enterprise on GitHub Enterprise Server. |
| Push Profile Update | Updates made to the user's profile in Okta will be pushed to GitHub Enterprise Server. |
| Push Groups | Groups in Okta that are assigned to the GitHub's application as Push Groups are automatically created in the enterprise on GitHub Enterprise Server. |
| Push User Deactivation | Unassigning the user from GitHub's application in Okta will disable the user on GitHub Enterprise Server. The user will not be able to sign in, but the user's information is maintained. |
| Reactivate Users | Users in Okta whose Okta accounts are reactivated and who are assigned back to GitHub's application on Okta will be enabled. |
Prerequisites
The general prerequisites for using SCIM on GitHub Enterprise Server apply. See the "Prerequisites" section in Configuring SCIM provisioning to manage users.
In addition:
-
To configure SCIM, you must have completed steps 1 to 4 in Configuring SCIM provisioning to manage users.
- You will need the personal access token (classic) created for the setup user to authenticate requests from Okta.
-
You must use Okta's application for both authentication and provisioning.
-
Your Okta product must support System for Cross-domain Identity Management (SCIM). For more information, review Okta's documentation or contact Okta's support team.
1. Configure SAML
Before starting this section, ensure you have followed steps 1 and 2 in Configuring SCIM provisioning to manage users.
In Okta
-
Go to the GitHub Enterprise Server application in Okta.
-
Click Add integration.
-
In the general settings, for the base URL, enter your GitHub Enterprise Server host URL (
https://HOSTNAME.com). -
Click the Sign On tab.
-
Ensure the "Credential Details" match the following.
- "Application username format": Okta username
- "Update application username on": Create and update
- "Password reveal": Deselected
-
In the "SAML Signing Certificates" section, download your certificate by selecting Actions, then clicking Download certificate.
-
On the right side of the page, click View SAML setup instructions.
-
Make a note of the "Sign on URL" and the "Issuer" URL.
On GitHub Enterprise Server
- Sign in to your GitHub Enterprise Server instance as a user with access to the Management Console.
- Configure SAML using the information you have gathered. See Configuring SAML single sign-on for your enterprise.
2. Configure SCIM
After configuring your SAML settings, you can proceed to configure provisioning settings.
Before starting this section, ensure you have followed steps 1 to 4 in Configuring SCIM provisioning to manage users.
-
Navigate to your GitHub Enterprise Managed User application on Okta.
-
Click the Provisioning tab.
-
In the settings menu, click Integration.
-
To make changes, click Edit.
-
Click Configure API integration.
-
In the "API Token" field, enter the personal access token (classic) belonging to the setup user.
Note
"Import Groups" is not supported by GitHub. Selecting or deselecting the checkbox has no impact on your configuration.
-
Click Test API Credentials. If the test is successful, a verification message will appear at the top of the screen.
-
To save the token, click Save.
-
In the settings menu, click To App.
-
To the right of "Provisioning to App", to allow changes to be made, click Edit.
-
Select Enable to the right of Create Users, Update User Attributes, and Deactivate Users.
-
To finish configuring provisioning, click Save.
When you have finished configuring SCIM, you may want to disable some SAML settings you enabled for the configuration process. See Configuring SCIM provisioning to manage users.
How do I assign users and groups?
After you have configured authentication and provisioning, you will be able to provision new users on GitHub by assigning users or groups to the relevant application in your IdP.
Note
A site administrator may have enabled API rate limits on your instance. 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 Troubleshooting identity and access management for your enterprise.
You can also automatically manage organization membership by adding groups to the "Push Groups" tab in Okta. When the group is provisioned successfully, it will be available to connect to teams in the enterprise's organizations. For more information about managing teams, see Managing team memberships with identity provider groups.
When assigning users, you can use the "Roles" attribute in the application on your IdP to set a user's role in your enterprise on GitHub Enterprise Server. For more information about the roles available to assign, see Roles in an enterprise.
Note
You can only set the "Roles" attribute for an individual user, not a group. If you want to set roles for everyone in a group that is assigned to the application in Okta, you must use the "Roles" attribute for each group member, individually.
How do I deprovision users and groups?
To remove a user or group from GitHub Enterprise Server, remove the user or group from both the "Assignments" tab and the "Push groups" tab in Okta. For users, make sure the user is removed from all groups in the "Push Groups" tab.