GitHub Enterprise Cloud Single Sign-On Rollout Guide

This guide has been created based on various scenarios encountered by others when enabling SSO. Its purpose is to help you ensure a smooth enablement process, minimizing issues, downtime, and any potential impact on your developers.

Requirements

Before you start integrating your IDP with your GitHub Enterprise Cloud Organization or Enterprise, Its important that your review the following requirements to ensure you have a successful setup.

Limitations

The main focus of this guide is 👀GitHub Enterprise Cloud and not for GitHub Enterprise Manager Users or GitHub Copilot(Exclusive) Enterprise account. However, to avoid any confusion we wanted to clarify some of the SAML / SCIM capabilities and limitations for each offering.

GitHub Enterprise Cloud offering Can SAML be configured at the Enterprise Level? Can SAML be configured at the Organizational Level? Is SCIM supported to provision and deprovision users?
GitHub Enterprise Cloud Yes Yes Only available at the organizational level, SCIM needs to be configured for each organization
GitHub Enterprise Managed Users Yes No Only available at the Enterprise level, Which enables you to provision and deprovision users to any organization within the Enterprise.
GitHub Copilot(Exclusive) Enterprise account Yes No Yes, At the Enterprise level. However, with this offering users are provisioned exclusively to the enterprise just to obtain access to GitHub Copilot. This offering is exclusively to grant and manage access to GitHub Copilot via your IDP. Users won't be able to create organizations or repositories.For more information on this offering and its limitations, please refer to Managing Copilot Business Licenses with an Enterprise Account

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.

Important considerations before configuring SAML/SCIM with GitHub Enterprise Cloud.

Before you enable/configure SSO we suggest you proceed on creating a test/staging environment. This can easily be done by creating a test organization. This will allow you to review and test the integration process without having any impact on your workflows, PATS, SSH Keys ,others and overall without affecting your developers. This will also help you understand how GitHub's SAML/SCIM works.

Think about GitHub Enterprise Cloud as a hierarchy. Hence, from a security perspective you are not losing any capabilities. Users collaborate at the organizational/repo level, The enterprise level is mainly used for configuring settings and policies that will apply to organizations that live within it. When a user is provisioned to an organization, automatically they are added to the enterprise because the organization lives within the enterprise. This allows you to centrally manage your license use and ensures a users only consumes a single license even if they are added to multiple repo or organizations within your enterprise.However, this does not grant them access to all resources within the Enterprise just to the ones they have been provisioned. View the enterprise level as your top-level management console.

graph TB
    A[Enterprise-Level]
    B[Organization A]
    C[Organization B]
    D[Repo A1]
    E[Repo A2]
    F[Repo A3]
    G[Repo B1]
    H[Repo B2]
    I[Repo B3]
    A --> B
    A --> C
    B --> D
    B --> E
    B --> F
    C --> G
    C --> H
    C --> I

We suggest you setup SAML/SCIM at the organizational level for multiple reasons but mainly due to the following:

  • Configuring SSO at the organizational level allows you to setup SCIM for provisioning and deprovisioning users.
  • You can create multiple organizations and decide if you want to enable SSO on it or not.
  • You can setup Team Sync which allows you to sync your IDP groups with specific GitHub Team's as a 1:1 mapping.
  • ⚠️ IMPORTANT ⚠️ If you enable SAML at the enterprise level you will not be able to setup SCIM as its not supported. Also this disables the capability of setting up SAML/SCIM at the organizational level.

Creating a test/sandbox organization

This section is completely optional but highly suggested. To proceed with the following you must be an Enterprise Owner if you are not an enterprise owner, please contact your GitHub enterprise owner so that they can grant you with this level of access.

  1. Login to GitHub.
  2. In the top-right corner of GitHub.com, click your profile photo, then click Your enterprises.
  3. In the list of enterprises, click settings next to the enterprise you want to view.
  4. Within your enterprise settings, click Organizations .
  5. Once you accessed the organization tab you will see the list of all your organizations. If its empty that is fine, it just means your Enterprise does not have any organizations yet. Within this panel click on New Organization and proceed on creating your new organization.
  6. Optionally, under Invite owners, type the username of a person you'd like to invite to become an organization owner, then click Invite.
  7. Click Finish.

Now that you have created the test/sandbox organization you can proceed on setting up SAML/SCIM on it without affecting your developers.

Setting up Single Sign-On

For details on how to setup SSO please refer to the following:


Passive Single Sign-On Rollout (SSO not enforced)

We understand that enabling SSO as soon as possible is a high-priority task as it will increase your security posture. However, before you do you must verify the following items to prevent possible inconveniences.

  1. Service Accounts: Any Service account or User account used for integration or that depends on using a Personal Access Token (PAT) for any CI/CD task including tasks performed by GitHub Actions will need to be reauthorized and authenticated via SSO. This must be done as soon as SSO is enabled. For details please refer to the following:

  2. Existing Users: After successfully enabling and configuring SSO and SCIM, existing members of the organization will be prompted to authenticate through SSO upon accessing the organization. All members must comply with this requirement to link their GitHub account to their IDP account, ensuring that access is not lost when SSO is fully enforced.

  3. New Users: Once SSO and SCIM are enabled and configured we highly advise that new users are provisioned exclusively via your IDP. Automatic provisioning depending on your IDP is done every 40-45 minutes, this is by default and hardcoded. If you wish to provision users instantly, provisioning on demand is available for both Azure AD and Okta. The provisioning flow of a new user is:
    1. User is added to your GitHub Enterprise Cloud - Organization application with your IDP.
    2. Once automatic provisioning occurs (or once the user is provisioned on demand) your IDP will provision the user to the GitHub Organization. This process will trigger an automated email to the user letting them know that they have been invited to join your GitHub Organization.
    3. Until the user accepts the invitation you will be able to see the user under: Organization> People> Invitation.
    4. Once the user accepts the invite they will be automatically redirected to GitHub. At this point they will be asked to verify their email before being able to accept the invite. While in their personal account their personal email might be verified they must also add their COMPANY/IDP email under Their profile settings > Emails.
    5. Add email address, here they must add their @companyemail.com
    6. Once added an email will be sent to their company email to verify it.
    7. After they verify their email they will be able to accept the invitation and join your organization.

    Extra: To avoid bullet point d and remove this step you can proactively request your users to add their @companyemail.com and verify it before enabling SAML/SSO in your organization.

  4. Verification of Linked Accounts: 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.
    1. Access your GitHub Organization, please ensure you are the owner or admin otherwise you will not be able to see this report.
    2. Within the organization access the “People” tab
    3. Within the People tab click on Export and choose CSV.
    4. A CSV report will be generated and downloaded. After it has downloaded, open the report.
    5. 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 their @companydomain.com meaning the field will be empty.

Enforcing Single Sign-On

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. 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. Therefore, it's essential to review and follow all the detailed action items mentioned under the Passive SAML/SCIM rollout to ensure a smooth transition. Failure to do so will have the following impact on your organization and its members:

⚠️ IMPORTANT ⚠️ It's critical to remove users with linked IDP accounts via SCIM from your IDP once SAML/SCIM is enforced. If a user is removed from GitHub but not from the IDP application, they can reinstate their access to the organization by authenticating against your IDP for up to three months. To do this, they simply need to access your Organizational URL, such as Https://github.com/{Organization_Name}/sso , which will automatically redirect them to authenticate against your integrated IDP. If their IDP account is still active and they're still provisioning the SSO application in your IDP, their account will be reinstated. This is not the case if their access is removed via SCIM. This behavior is set by default and cannot be changed. For details please refer to Reinstating a former member of your organization - GitHub Enterprise Cloud Docs

For further information feel free to review our documentation on Enforcing SAML single sign-on for your organization - GitHub Enterprise Cloud Docs. We also highly recommend that before you enforce SSO you validate all setting in a Stagining / Test Organization as mentioned under “Passive Single Sign-On Rollout (SSO not enforced)”

SSO Additional Feature (Team Sync)

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

As per its limitation, it is 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 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 can be provisioned

Informing your developers

The email template below has been created towards helping you inform your developers of the changes once you rollout SSO. This is just a template to give you an idea on what to include in your communication to them.

Subject: Single Sign-On (SSO) Enabled for GitHub Organization

Dear {GitHub Users},

We're excited to announce that we have enabled Single Sign-On (SSO) for our GitHub organization. This means that from now on, all authentication attempts for our organization's members will be directed to our SSO provider.

This recent change affects how you access and authenticate against GitHub. Therefore, it's crucial that you review the following information and take any necessary actions that apply to you.

Enabling and enforcing SSO means that all members of the organization must authenticate through our Identity Provider (IdP) to access the organization's resources. Therefore, after SSO is enabled in GitHub, you will see a banner requesting that you authenticate via SSO. It's crucial that you do so to bind your GitHub account with your company email. This will ensure that you can access the organization's resources seamlessly and securely. Failure to do so will cause your access to the organization and its resources to be revoked as soon as SSO is enforced.

If you have any questions or concerns regarding this change please feel free to contact us at {IT@Companyxyz.com}

Best Regards,

{Signature | Email | Etc}