GitHub Enterprise Cloud - OKTA Single Sign-On (SSO) Integration Guide

Made by Jack G Kafaty Senior Solutions Engineer @GitHub

Requirements

👀 Lets get started the right way!

Before you start integrating Okta with your GitHub Enterprise Cloud Organization or Enterprise, Its important that your review the following requirements to ensure you have a successful setup. If you do not see any settings for your organization or enterprise make sure you have owner rights.


Recommendations

👀 You might want to give this a read
  • ⚠️ IMPORTANT ⚠️ If you are configuring SSO at the ORGANIZATIONAL level please use the following following Okta application from the App Catalog - GitHub Enterprise Cloud - Organization. This is the only application that will allow you to configure the correct SAML attributes and have SCIM capabilities (provisioning and deprovisioning capabilities) for your GitHub Enterprise Cloud Organization.

  • ⚠️ IMPORTANT If you are configuring SSO at the ENTERPRISE level please use exclusively the following Okta application from the App Catalog - Github Enterprise Cloud - Enterprise Accounts. This is the only application that will allow you to configure the correct SAML attributes for your GitHub Enterprise Cloud Enterprise Account.

  • Validate you have the correct permissions to make changes to your GitHub Enterprise Cloud Organization / Enterprise and Okta organization.

  • If you are using a single monitor, we recommend you open two separate browser windows and place them side-by-side. Meaning have your GitHub Organizational / Enterprise settings on one side of your screen and your Okta settings on the other side of your screen. This will allow you to easily navigate between the two applications and ensure you are following the steps correctly.

  • Please avoid testing any of the configurations until you have completed the entire setup. This will ensure you have a successful setup and avoid any issues.

Official & Helpful Documentation


Enterprise-level vs Organizational-level SSO integration - What's the difference?

Feature Enterprise Level SSO Organizational Level SSO
SCIM support No , There is no support for provisioning or deprovisioning of users. Yes, Fully supports user provisioning and deprovisioning.
SSO Automatically enforced Required for all organizations and resources. Optional, can be enabled and enforced on a per-organization basis allowing further flexibility during setup.
Multiple IDP integration No. Yes, you can configure different supported IDPs per organization.


GitHub Enterprise Cloud - Organizational-level setup tutorial video


GitHub Enterprise Cloud - Organizational-level TeamSync tutorial video



GitHub Enterprise Cloud | Organizational-level Okta SSO Setup Step-by-Step!

Step 1: Adding the GitHub Enterprise Cloud Application from the Okta App catalog
  1. Login to your Okta's Organization Admin portal, Make sure that you have the sufficient Administrator permissions. Within the Admin portal on the left-side menu bar access Applications

  2. Within Browser App Catalog search for Github Enterprise Cloud - Organization, select it and Click on Add

  3. Under General Settings, add the name of your GitHub Organization under GitHub Organization and click Done.

Step 2: Okta Baseline SAML Configuration
  1. With the GitHub Enterprise Cloud Application selected, click on Sign On and then click on View Setup Instructions.


  2. Once you see the specific SAML setup instructions for your application, copy the following values from Step 4 into a notepad:
    • Sign on URL
    • Issuer
    • Public Certificate


Step 3: Adding Users and Groups
  1. Within the GitHub Enterprise Cloud Application in Okta, select Assignments and click on Assign to add a user or group that should have access.
    • If you are the organizational owner, add yourself for now.
    • If you plan on using a service account, add the service account instead. Note that you will also need to create a service account user within your GitHub Organization and add it as an Owner/Admin to your organization. This will consume a user license.


Step 4: Login and Access the Settings
  1. Login to your GitHub account. Make sure you are an Enterprise or Organizational owner.


  2. In GitHub, click on the dropdown next to your profile image in the top-right corner. Select “Your Organizations” from the dropdown. You will be redirected to your profile's organizational access overview, which will display all the organizations you have access to. Click on Settings next to the organization you will be integrating Okta SSO with.


Step 5: Configuring SAML
  1. Go to Security in the organization settings menu on the left, and click on Authentication Security. Then, click on Enable SAML authentication.

  2. Once SAML is enabled, fill out the information based on the SAML configuration settings from Step 2: Okta Baseline SAML Configuration.

  3. Click on Test SAML Configuration and proceed to login to complete the setup.

  4. Once you have successfully authenticated via Okta's SSO, you should see a positive message stating that you have successfully authenticated your SAML SSO identity. Click on Save! to complete your setup.
Step 6 (Optional): Enabling / Configuring SCIM to provision and deprovision users
  1. Access Okta as an Admin/Super Admin and go to Applications.
  2. Select the GitHub Enterprise Cloud application you configured in previous steps.
  3. Within the application, select Provisioning and click on Configure API Integration.


  4. Click on Enable API Integration and then click on Re-authenticate with GitHub Enterprise Cloud (name of your SSO application).


  5. Grant access to the GitHub Organization you are enabling SSO and click Continue.


  6. Once completed, you will be redirected back to Okta and you should see a message stating that your Organization was verified successfully. Click on Save.


  7. Click on ”Edit” and enable the following app provisioning settings:
    • Create Users
    • Update User Attribute
    • Deactivate Users


  8. Once enabled, click Save.


Step 7 (Optional): Creating an Okta Security Token to enable Team Synchronization
  1. To enable Team Sync on GitHub, you need to create an API token on Okta. Here's how:
    • In Okta, go to Security > API.
    • On the API panel, select Token and click on Create Token.
    • Copy the token into a notepad as you will need it later on.


  2. Once completed, the token created should look like the image below.


Step 8 (Optional): Enabling Team Synchronization
  1. Login to your GitHub account as an Enterprise or Organizational owner.


  2. In GitHub, click on the dropdown next to your profile image in the top-right corner. Select “Your Organizations” from the dropdown. Click on Settings next to the organization you integrated Okta SSO in previous steps.


  3. In the Organizational settings, select Authentication Security and scroll down to Team Synchronization. Click on Enable for Okta.


  4. Enter the SSWS Token generated in Okta and the URL that refers to your Okta's organization URL. Click update/save.


  5. Team Sync is now successfully enabled.


Step 9 (Optional): Enforcing Single Sign-On
  1. Once your SAML configuration is completed click on Single Sign-on to SSO into GitHub Once done you will be able to enforce SSO


  2. Once completed click on Save

    3. ⚠️WARNING⚠️ Before Enforcing SSO we highly advice that you review the full impact this will have within your organization and its overall access. You can review specific details by reviewing "What is the overall impact when enforcing SSO?" within this document under Okta SSO Specific Frequently Asked Questions


GitHub Enterprise Cloud | Enterprise-level Okta Setup Step-by-Step!

Step 1: Adding the GitHub Enterprise Cloud Application from the Okta App Catalog
  1. Login to your Okta's Organization Admin portal with sufficient Administrator permissions. Access Applications from the left-side menu bar.


  2. In the Browser App Catalog, search for Github Enterprise Cloud - Enterprise, select it and click on Add.


  3. Under General Settings, add the name of your GitHub Enterprise under GitHub Enterprise and click Done.


Step 2: Okta Baseline SAML Configuration
  1. With the GitHub Enterprise Cloud Application selected, click on Sign On and then click on View Setup Instructions.


  2. Once you see the specific SAML setup instructions for your application, copy the following values from Step 4 into a notepad:
    • Sign on URL
    • Issuer
    • Public Certificate


Step 3: Adding Users and Groups
  1. Within the GitHub Enterprise Cloud Application in Okta, select Assignments and click on Assign to add a user or group that should have access.
    • If you are the Enterprise owner, add yourself for now.
    • If you plan on using a service account, add the service account instead. Note that you will also need to create a service account user within your GitHub Enterprise and add it as an Owner/Admin to your Enterprise.


Step 4: Login and access the settings
  1. Login to your GitHub account, Please ensure you are an Enterprise owner.


  2. Within GitHub on the top-right corner click on dropdown next to you profile image. Within the dropdown select Your Enterprises. Once done, you will be redirect to your profile's Enterprise access overview which will display all the Enterprises you have access too. Click on settings next to the Enterprise you will be integrating Okta SSO.


Step 5: Configuring SAML
  1. Within your Enterprise's settings on the left-side menu under Settings click on Authentication Security. Afterwards click on Enable SAML authentication
  2. Once SAML is enabled, fill out the information based on the SAML configuration settings from Step 2: Okta Baseline SAML Configuration.


  3. Click on Test SAML Configuration and proceed on login to complete the setup.
  4. Once you have successfully authenticated via Okta's SSO you should see a positive message stating that you have successfully authenticated your SAML SSO identity. Click on Save! to complete your setup!


  5. After Click on Save! as a final step you will be requested to Download / Print / Copy your recovery codes. This codes are unique and can be used to regain access to your enterprise without SSO in the scenario you need to. Once you select an option you will be able to click on Enable SAML Authentication. From this point forward all users must authenticate via SAML to obtain access to your Enterprise and all Organizations within it. With the exception of Outside Collaborators unless you provision them as normal users.


Step 6 (Optional): Creating an Okta Security Token to enable Team Synchronization at the Enterprise Level
  1. To enable Team Sync on GitHub, you need to create an API token on Okta. Here's how:
    • In Okta, go to Security > API.
    • On the API panel, select Token and click on Create Token.
    • Copy the token into a notepad as you will need it later on.


  2. Once completed, the token created should look like the image below.


Step 7 (Optional): Team Synchronization
  1. Once your SAML configuration is completed you can proceed on enabling Team Sync by clicking on Enable for Okta


  2. Once you click on Enable for Okta you will be redirected to enter the Okta Application Credentials for Team Sync.


  3. Once done you will be redirected back to your Enterprise's Authentication settings. You should see a confirmation banner stating Team Synchronization Settings have been updated


  4. Finally you will notice you will now see the option to disable team synchronization, meaning it has now been fully enabled. Click on Save to complete your setup!



⚠️ IMPORTANT ⚠️

  • SCIM capabilities to provision and deprovision users is not supported when configuring SAML at the Enterprise Level. This is only supported at the Organizational Level. If you wish to provision and deprovision users from your IDP you must configure SAML and SCIM for each Organization within your Enterprise.

  • SSO is enforced by default at the Enterprise Level, meaning that all users must authenticate via SAML to obtain access to your Enterprise and all Organizations within it. With the exception of Outside Collaborators unless you provision them as normal users.



Okta SSO Specific Frequently Asked Questions

1. What will happen to existing users when I enable SSO?

After successfully enabling and configuring SSO and SCIM, existing members of the organization will be prompted to authenticate through SSO upon accessing the organization. It's imperative that all members comply with this requirement to link their GitHub account to their IDP account, ensuring that access is not lost when SSO is fully enforced. For further details refer to [Enabling and testing SAML single sign-on for your organization - GitHub Enterprise Cloud Docs](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-saml-single-sign-on-for-your-organization/enabling-and-testing-saml-single-sign-on-for-your-organization)


2. Can someone get on a call with me to achieve this setup?

Hands-on Keyboard or dedication session assistance is only offered to customers under our Premium Support Plan or customers who have opted for a white-glove Professional Service engagement . If you are interested in learning more about our Premium Support Plan or Professional Services please reach out to your GitHub Account Manager for pricing details. For Enterprise Customers without a Premium Support Plan or Professional Services engagement, please reach out to our GitHub Enterprise Support Team for assistance using the following [LINK](https://support.github.com/).


3. If I enable SSO at the Enterprise-level and later on add an organization, what will happen?

For details please refer to [Adding organizations to your enterprise](https://docs.github.com/en/enterprise-cloud@latest/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/adding-organizations-to-your-enterprise)


4. What is the overall impact when enforcing SSO?

Enforcing SAML means that all members of the organization will need to authenticate against your IDP to access the organization and its resources, Excluding outside collaborators , [Adding outside collaborators to repositories in your organization - GitHub Enterprise Cloud Docs](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-user-access-to-your-organizations-repositories/adding-outside-collaborators-to-repositories-in-your-organization) . It's crucial to note that enforcing SAML will have an impact on all SSH keys, PATs, and OAuth applications that were created, integrated, or configured before SSO was enabled. As well its important to highlight: - Users who did not link their GitHub account with your IDP will be automatically removed from the organization, hence will lose access to all resources and would need to be provisioned again. - Any CI/CD task that depends on a Personal Access Token that has not been authenticated against SSO will fail due to authentication failure. Hence causing your automation/pipeline to break. [Authorizing a personal access token for use with SAML single sign-on - GitHub Enterprise Cloud Docs](https://docs.github.com/en/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on) - Developers who use SSH keys to access resources via the GitHub CLI will not be able to access resources until their SSH keys are authenticated. [Authorizing an SSH key for use with SAML single sign-on - GitHub Enterprise Cloud Docs](https://docs.github.com/en/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/authorizing-an-ssh-key-for-use-with-saml-single-sign-on) - 0Auth applications/Integration will break until they are reauthorized against SSO. [Authorizing OAuth Apps - GitHub Enterprise Cloud Docs](https://docs.github.com/en/enterprise-cloud@latest/apps/oauth-apps/using-oauth-apps/authorizing-oauth-apps) - Bots and service accounts that do not have external identities set up in your organization's IdP will also be removed when you enforce SAML SSO. For more details please refer to [Managing bots and service accounts with SAML single sign-on - GitHub Enterprise Cloud Docs](https://docs.github.com/en/enterprise-cloud@latest/organizations/granting-access-to-your-organization-with-saml-single-sign-on/managing-bots-and-service-accounts-with-saml-single-sign-on) For more details please review our official documentation on [Enforcing SAML single sign-on for your organization](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-saml-single-sign-on-for-your-organization/enforcing-saml-single-sign-on-for-your-organization) Note: The above impact will be the same when configuring SSO at the Enterprise Level


5. How can I see which users have linked their GitHub account with their Okta SSO ID?

Once your users have been informed and they have proceeded on linking their GitHub account with your IDP. You can download a report to validate which users have completed this step and which ones have not. It's important that you do this before enforcing SSO, as users who have not linked their account once SSO is enforced their user account will be removed from the organization: - A. Access your GitHub Organization, please ensure you are the owner or admin otherwise you will not be able to see this report. - B. Within the organization access the “People” tab - C. Within the People tab click on Export and choose CSV. - D. A CSV report will be generated and downloaded. After it has downloaded, open the report. - E. In the report there are only 2 columns you should focus on, “Login” and “Saml_name_id”. The login column will display the users GitHub handle/username and the Saml_name_id will display their @companydomain.com email only if they have linked their GitHub account with your IDP. if they have not the Saml_name_id will not display For further information feel free to review our documentation on [Preparing to enforce SAML single sign-on in your organization - GitHub Enterprise Cloud Docs](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-saml-single-sign-on-for-your-organization/preparing-to-enforce-saml-single-sign-on-in-your-organization)

6. What are Team Sync's Limitations?

Team Sync is a feature that allows you to sync your IDP group to a GitHub team. Think about it as a 1-1 mapping 1 IDP group per GitHub Team. For more information on its capabilities feel free to review our documentation on [Synchronizing a team with an identity provider group - GitHub Enterprise Cloud Docs](https://docs.github.com/en/enterprise-cloud@latest/organizations/organizing-members-into-teams/synchronizing-a-team-with-an-identity-provider-group) As per its limitation it important to highlight the following: - Nested groups are not supported by Team Sync. Parent teams cannot synchronize with IdP groups. If the team you want to connect to an IdP group is a parent team, we recommend creating a new team or removing the nested relationships that make your team a parent team IDP groups with more than 5,000 members are not supported. - Maximum number of members in a GitHub organization: 10,000 - Maximum number of teams in a GitHub organization: 1,500 - Once a GitHub team is connected to an IdP group, your IdP administrator must make team membership changes through the identity provider. You cannot manage team membership on GitHub Enterprise Cloud or using the API. - By default, team synchronization does not invite non-members to join organizations, which means that a user will only be successfully added to a team if they are already an organization member. - The person has already logged in with their personal account on GitHub Enterprise Cloud and authenticated to the organization via SAML single sign-on at least once to link their account. - Only IDP members with linked accounts are able to be provisioned

7. How frequent are user provisioned via SCIM?

User/Group provisioning is done on a fixed Hard-Coded interval of 40 Minutes.

8. I'm unable to integrate Okta AD SSO I keep on getting errors

Please reach out to our support team at [GitHub Enterprise Support](https://support.github.com/) and provide them with: - Screenshot of the issue or error message. - Screenshot of your Okta SAML configuration. - Screenshot of your GitHub SSO configuration. - Screenshot of the application you selected during our setting. - Let them know if you are integrating SSO at the organizational level or the Enterprise level.