Configuring SAML single sign-on and SCIM for your enterprise account using Okta

You can use Security Assertion Markup Language (SAML) single sign-on (SSO) and System for Cross-domain Identity Management (SCIM) with Okta to automatically manage access to your enterprise account on GitHub.

Enterprise accounts are available with GitHub Enterprise Cloud and GitHub Enterprise Server. For more information, see "About enterprise accounts."

In this article

Did this doc help you?

Help us make these docs great!

All GitHub docs are open source. See something that's wrong or unclear? Submit a pull request.

Make a contribution

Or, learn how to contribute.

Note: User provisioning for enterprise accounts is currently in private beta and subject to change. To request access to the beta, contact our account management team.

About SAML and SCIM with Okta

You can control access to your enterprise account in GitHub and other web applications from one central interface by configuring the enterprise account to use SAML SSO and SCIM with Okta, an Identity Provider (IdP).

SAML SSO controls and secures access to enterprise account resources like organizations, repositories, issues, and pull requests. SCIM automatically adds, manages, and removes members' access to organizations owned by your enterprise account when you make changes in Okta. For more information, see "Enforcing security settings in your enterprise account."

After you enable SCIM, the following provisioning features are available for any users that you assign your GitHub Enterprise Cloud application to in Okta.

FeatureDescription
Push New UsersNew users created in Okta will gain access to enterprise account resources, and can optionally be automatically invited to any of the organizations owned by the enterprise account
Push User DeactivationDeactivating a user in Okta will revoke the user's access to the enterprise account resources and remove the user from all organizations owned by the enterprise account
Push Profile UpdatesUpdates made to the user's profile in Okta will be pushed to the user’s enterprise account metadata
Reactivate UsersReactivating the user in Okta will re-enable the user's access to the enterprise account and will optionally send email invitations for the user to rejoin any of the organizations owned by the enterprise account that the user was previously a member of

Prerequisites

You must use the "Classic UI" in Okta. For more information, see Organized Navigation on the Okta blog.

Selecting "Classic UI" from Okta UI style picker above dashboard

Adding the GitHub Enterprise Cloud application in Okta

  1. In Okta, in the upper-right corner, click Admin.
    Admin button in Okta
  2. In the Okta Dashboard, click Applications.
    "Applications" item in the Okta Dashboard navigation bar
  3. Click Add application.
    "Add application" button in the Okta Dashboard's Applications tab
  4. In the search field, type "GitHub Enterprise Cloud".
    Okta's "Search for an application" field
  5. Click "GitHub Enterprise Cloud - Enterprise Accounts".
  6. Click Add.
  7. Optionally, to the right of "Application label", type a descriptive name for the application.
    Application label field
  8. To the right of "GitHub Enterprises", type the name of your enterprise account. For example, if your enterprise account's URL is https://github.com/enterprises/octo-corp, type octo-corp.
    GitHub Enterprises field
  9. Click Done.

Enabling and testing SAML SSO

  1. In Okta, in the upper-right corner, click Admin.
    Admin button in Okta
  2. In the Okta Dashboard, click Applications.
    "Applications" item in the Okta Dashboard navigation bar
  3. Click the label for the application you created for your enterprise account.
  4. Assign the application to your user in Okta. For more information, see Assign applications to users in the Okta documentation.
  5. Under the name of the application, click Sign on.
    "Sign on" tab for Okta application
  6. To the right of Settings, click Edit.
  7. Under "Configured SAML Attributes", to the right of "groups", use the drop-down menu and select Matches regex.
  8. To the right of the drop-down menu, type .*.*.
  9. Click Save.
  10. Under "SIGN ON METHODS", click View Setup Instructions.
    "View Setup Instructions" button in Okta application's "Sign On" tab
  11. Enable SAML for your enterprise account using the information in the setup instructions. For more information, see "Enforcing security settings in your enterprise account."

Creating groups in Okta

  1. In Okta, create a group to match each organization owned by your enterprise account. The name of each group must match the account name of the organization (not the organization's display name). For example, if the URL of the organization is https://github.com/octo-org, name the group octo-org.
  2. Assign the application you created for your enterprise account to each group. GitHub will receive all groups data for each user.
  3. Add users to groups based on the organizations you'd like users to belong to.

Configuring user provisioning with SCIM in Okta

If you're participating in the private beta for user provisioning for enterprise accounts, when you enable SAML for your enterprise account, SCIM provisioning and deprovisioning is enabled by default in GitHub. You can use provisioning to manage organization membership by configuring SCIM in your IdP.

To configure user provisioning with SCIM in Okta, you must authorize an OAuth application to create a token that Okta can use to authenticate to GitHub on your behalf. The okta-oauth application is created by Okta in partnership with GitHub.

  1. In Okta, in the upper-right corner, click Admin.
    Admin button in Okta
  2. In the Okta Dashboard, click Applications.
    "Applications" item in the Okta Dashboard navigation bar
  3. Click the label for the application you created for your enterprise account.
  4. Under the name of the application, click Provisioning.
    "Provisioning" tab for Okta application
  5. Click Configure API Integration.
    "Configure API Integration" button for Okta application
  6. Select Enable API integration.
    "Enable API integration" checkbox for Okta application
  7. Click Authenticate with Github Enterprise Cloud - Enterprise Accounts.
    Button to authenticate with GitHub
  8. To the right of your enterprise account's name, click Grant.
  9. Click Authorize okta-oauth.
  10. Click Save.
    "Save" button for Okta application's provisioning configuration
  11. To the right of "Provisioning to App", click Edit.
    "Edit" button for Okta application's provisioning options
  12. To the right of "Create Users", select Enable.
    "Enable" checkbox for Okta application's "Create Users" option
  13. To the right of "Update User Attributes", select Enable.
    "Enable" checkbox for Okta application's "Update User Attributes" option
  14. To the right of "Deactivate Users", select Enable.
    "Enable" checkbox for Okta application's "Deactivate Users" option
  15. Click Save.
    "Save" button for Okta application's provisioning configuration
  16. Under the name of the application, click Push Groups.
    Push Groups tab
  17. Use the Push Groups drop-down menu, and select Find groups by name.
    Push Groups drop-down menu
  18. Add a push group for each organization in your enterprise account that you want to enable user provisioning for.
    • Under "PUSH GROUPS BY NAME", search for a group that corresponds to an organization owned by your enterprise account, then click the group in the search results.
    • To the right of the group name, in the "Match results & push action" drop-down menu, verify that Create Group is selected.
      Match result drop-down with Create Group selected
    • Click Save.
    • Repeat for each organization.
  19. Under the name of your application, click Assignments.
    Assignments tab
  20. If you see Provision users, users who were a member of an Okta group before you added a push group for that group have not been provisioned. To send SCIM data to GitHub for these users, click Provision users.

Enabling SAML user provisioning

After you enable SCIM provisioning and deprovisioning, you can optionally enable SAML user provisioning and deprovisioning.

  1. In the top-right corner of GitHub, click your profile photo, then click Your enterprises.

    "Your enterprises" in drop-down menu for profile photo on GitHub

  2. In the list of enterprises, click the enterprise you want to view.

    Name of an enterprise in list of your enterprises

  1. In the enterprise account sidebar, click Settings.
    Settings tab in the enterprise account sidebar
  2. In the left sidebar, click Security.
    Security tab in the enterprise account settings sidebar
  3. Under "SAML User Provisioning", select Enable SAML user provisioning.
    Checkbox to enable user provisioning with SAML
  4. Click Save.
  5. Optionally, enable SAML user deprovisioning.
    • Select Enable SAML user deprovisioning, then click Save.
      Checkbox to enable user deprovisioning with SAML
    • Read the warning, then click Enable SAML deprovisioning.
      Enable SAML deprovisioning button

Did this doc help you?

Help us make these docs great!

All GitHub docs are open source. See something that's wrong or unclear? Submit a pull request.

Make a contribution

Or, learn how to contribute.