GitHub Enterprise Cloud Enterprise Managed Users - Microsoft Entra ID / Azure AD Single Sign-On (SSO) Integration Guide

GitHub Enterprise Cloud logo

Made by Jack G Kafaty Senior Solutions Engineer @GitHub

Requirements

Before you start integrating Microsoft Entra ID / Azure AD with your GitHub Enterprise Cloud - Enterprise Manage User tenant, it's important that you 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 ⚠️ For this setup on the GitHub side of things MUST be done using an incognito window / private browser. If you do not want to do this using an incognito / private browser, Please logout from GitHub.com completely. Once done access your GitHub Enterprise Managed User tenant using the direct URL, such as: https://github.com/enterprises/(YOUR_ENTERPRISE_MANAGED_USER_ENTERPRISE_NAME) and login with the admin account.
  • Validate that you have access to the admin account for your GitHub Enterprise Cloud Enterprise Managed Users tenant, This is NOT your normal GitHub account, This login had to be sent to you from support@github.com. The username for such account look as the following : EmuName_admin.
  • ⚠️ IMPORTANT ⚠️ Please use exclusively the following Microsoft Entra ID / Azure AD application from the App Catalog - GitHub Enterprise Managed User. 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 Enterprise Managed Users tenant.
  • Please follow the steps as they are, failure to do so will result in multiple errors, invalid configurations and overall could increase the complexity of your setup.

Official & Helpful Documentation

GitHub Enterprise Managed Users - Document Hub

Microsoft Entra ID / Azure AD setup guides

Step by Step Guide!

Welcome to GitHub Enterprise Cloud - Enterprise Managed Users

Step 1: Welcome to GitHub Enterprise Cloud - Enterprise Managed Users Email

  1. Once your GitHub Enterprise Cloud - Enterprise Managed User tenant is created you will receive an email containing detailed instructions on setup your enterprise and integrate your IDP. The instructions provided are basically the steps that we will be following in this guide. However from this email you need some important information which are highlighted below:
    • Admin Username: You will need this to access your GitHub Enterprise Cloud - Enterprise Managed User tenant and integrate your IDP.
    • Enterprise-Name: This is mainly for reference
    • Enterprise-URL: This is the direct URL to access your GitHub Enterprise Cloud - Enterprise Managed User tenant


  2. You should also see a second email sent by support@github.com with the subject [GitHub] You've been added as an owner of the (Your_EnterpriseName) enterprise. This email contain a a direct link to set the password for your Enterprise Managed Users - Admin account
    ⚠️ IMPORTANT ⚠️
    • This link will expire in 24 hours from the moment you receive the email.
    • We strongly recommend that you right-click the set your password button and copy the link within.


  3. Once you have copied the link open a private/incognito window and paste the link there to access it and reset the admin's account password


  4. After changing your admin's user password you will receive a confirmation email from noreply@github.com with the subject [GitHub] Your password was reset This is just informative and no action is needed at this time.


  5. At this point you are ready to access your GitHub Enterprise Cloud - Enterprise Managed Users tenant

Integrating SAML and SCIM

Step 2: Accessing your Managed Users Enterprise

  1. In a private or incognito browser access your GitHub Enterprise Cloud - Enterprise Managed Users tenant by using the URL provided on the setup instructions email located under Enterprise-URL

  2. Once done you may see a landing page with the message 404 This is not the web page you are looking for. Don't worry this is expected. Proceed on clicking the Sign In button, located on the top-right corner or center of the screen depending if this is the first time you are accessing your enterprise or if you are returning to continue your setup.


  3. You should see a login pop-up appear, please proceed on inputting your admin credentials Do not enter your GitHub account credentials as this will not work. You will only be able to access at the moment using the admin username provided on your setup instructions email and using the password you set when you reset the password for the the Enterprise Managed Users admin account. .


  4. Once done you will be taken to a second factor authentication screen which will require you to input a device verification code. This code will be sent to the same email in which you received your admin user password reset link and your setup instructions. Input the verification code from the email into GitHub's device verification and click on verify


  5. After your verification code is accepted you will be logged in, However it might not seem that way because the UI might display 404 This is not the web page you are looking for screen.The view/landing page depends on if you have already logged in once but did not setup Single Sign On or if its the first time you are accessing your Enterprise tenant. However, if you already logged in once and are returning to complete your setup notice on the top-right corner it no longer shows Sign In but you do see a green 8-bit profile icon! Click it
    6. First time accessing your Enterprise view.
    Returning to complete your setup Enterprise view.

Step 3: Generating a dedicated Personal Access Token for SCIM provisioning

  1. If your are accessing your Enterprise tenant for this first time, your default view once logged in should be your Enterprise tenat's Overview page. If you are returning to complete your setup, after you login you will see the 404 page. Disregarding if you are returning to complete your setup or accessing your tenant for the first time the following steps remain the same.Within the Admin user's profile right-hand menu bar click on Settings.

    First time accessing your setup - View

    Returning to complete your setup - View

  2. Within the Admin user's profile settings access Developer Settings, located at the bottom-left corner


  3. In the Developer settings click on Personal Access Tokens and then on Tokens Classic followed by Generate a new token located on to the top right-corner and from that dropdown select Generate New token (Classic)


  4. Select No expiration in the Expiration Drop Down.


  5. Scroll down and locate scim:enterprise and click on the checkbox to select it. Once done click on Generate Token


  6. Once done your token will be generated Copy/store this token in a safe place , this token will not show up again. If you lose this token you will need to generate a new one. After copying/storing your token feel free to exit the Admin user's developer settings.


Step 4: Adding the GitHub Enterprise Managed Users Application from the Marketplace

  1. Login to your Azure Portal, Make sure that you have Administrator permissions


  2. Access “Enterprise Applications”


  3. Within Enterprise Applications, Click on New Application

  4. Within the Azure AD gallery search for GitHub Enterprise Managed Users

  5. Once Selected click create at the bottom left-side corner.


Step 5: Setting up SAML within the GitHub Enterprise Managed Users application in Azure AD

  1. Within the GitHub Enterprise Managed User App select option 2. Set up single sign on.


  2. Within the Single Sign-on select SAML as the Single Sign-on method.


  3. Within the SAML configuration click edit on the Basic SAML Configuration.


  4. Under the basic SAML configuration, make sure you enter the correct values for example:
    •   Identifier (Entity ID) = https://github.com/enterprises/Your_Enterprise_Name
    •   Reply URL= https://github.com/enterprises/Your_Enterprise_Name/saml/consume
    •   Sign on URL= https://github.com/enterprises/Your_Enterprise_Name/sso 

      • ⚠️NOTE: You might get a prompt to test the SAML configuration! Let's not do that now as it will fail. Remember we are still missing to configure SAML on GitHub.⚠️


  5. Under SAML Signing Certificate, download the Base64 Certificate and open it using your code editor of choice. Keep it handy as we will need it later during this guide.


  6. Under Set up GitHub Enterprise Managed Users, within the Azure AD SAML configuration copy the following values and keep them handy as we will also need them later on during this guide.
    • Login URL
    • Microsoft Entra ID identifier


Step 6: Adding Users and Groups

  1. Within the SAML configuration page on Azure AD, at left-side menu under "Manage" access "Users and groups”


  2. Click on Add user/group and proceed on adding your users or groups who will be authenticating via SAML in GitHub. It’s important that while doing this setup you must add your user and make sure your user has global administrator privileges in order to successfully complete the setup.


  3. To add users or groups, simple search for the name of the user/group you wish to grant access. You will also need to select a role. Its important that you select Enterprise Owneras the role. Once done click Assign


  4. Finally, your assigned user should look like the following.


Step 7: Enabling and configuring SSO in GitHub

  1. Access your Admin user's profile menu by click on the top-right 8-bit profile image. Within the menu click on Your Enterprises.


  2. Once done you should be taken back to your Enterprise tenant's Overview landing page.


  3. In your Enterprise Overview located at the left-side menu panel click on Identity Provider and from the expanded menu click on Single sign-on configuration ( should be selected by default) Within the Single sign-on configuration panel, proceed on selection the option that fits your needs. For this guide we will be selecting SAML single sign-on . To proceed click on Add SAML configuration .


  4. Within the SAML configuration panel you will need to fill out the required information with the values obtained from the previous step when setting up SAML in Microsoft ENTRA ID. Which provided you the values below for your application:
    • Sign On URL

    • Issuer

    • Public Certificate


  5. Once you complete filling out the needed information to setup SAML click on Test SAML Configuration You will be redirected to Microsoft Entra ID to login. Please login using the account that was assigned on previous steps within this guide.


  6. After successfully authenticating against Microsoft Entra ID / Azure AD you should see a banner on top displaying the message Your SAML provider settings have been validated. Remember to save your changes and right next to Test SAML Configuration you should see Passed successfully authenticated your SAML SSO identity


  7. At this point click on Save SAML Settings to save your changes. Once done you will be redirected to store your Single Sign-On recovery codes Please save them as you might need them at a future time. Once you click on either Download / Print/ Copy The Enable SAML authentication Will become available. When it does please click on it to enable SAML and proceed further.


  8. Single Sign-On is enabled but we are not done!

    After your store your recovery codes you will be redirected to your Single sign-on configuration page will you will now see SAML Single -sign-on ON .


Step 8: Configuring SCIM in Microsoft Entra ID / Azure AD for user/group provisioning and deprovisioning

  1. Login to your Azure Portal and Search for the GitHub Enterprise Managed Users application under Enterprise Applications created in Step 4 in this guide. Once identified click on it to access its settings.


  2. Within the settings locate provisioning located on lef-side menu bar under Manage and Click on provisioning to access the provisioning settings


  3. Within Provisioning click on Get Started


  4. On the Provisioning Settings set the following values:
    •   Provisioning Mode = Automatic
    •   Admin Credentials = https://api.github.com/scim/v2/enterprises/YOUR_ENTERPISE_NAME
    •   Secret Token = This is the personal access token created in step 3
    Once you finish setting up the values click on Testing your Connection by clicking on Test Connection. Once completed you should see a pop-up on the top-right corner stating that the test was successful. Finally click on Save and navigate back to provisioning by clicking the Navigation hyperLinks located above provisioning.


  5. Once you are redirected back to the Provisioning Overview Click on Start Provisioning. Afterwards you should see a successful confirmation message on the top right corner informing you that provisioning has started. Keep in mind that only the users added within Users and Groups will be provisioned at this time. Any other user added later on will be added based on the Hard-coded scheduled cron which runs every 45 minutes, this can not be changed. However you can skip the cron by clicking on Provision on demand, to provision users or groups immediately


  6. Finally, Once provisioning has started your user should be provision. This is the user we assigned as the Enterprise Owner in step 6. If you do not see the UI update after a couple of seconds do click on refresh. Your should see the following view.


Step 9: Accessing GitHub as Provisioned user and validating settings

  1. Lets go back to your GitHub Enterprise Cloud Enterprise Managed Users tenant. On the left-side menu panel click on People within People from the expanded menu click on Members (should be the default option). From there you should be able to see your provisioned user.


  2. Once you are able to see your provisioned user this means Your setup has been completed, Congrats! At this point we suggest you logout from the admin user and login with your provisioned user.




Microsoft Entra ID / Azure AD Frequently Asked Questions

1. 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.


2. What are IDP Group Limitations?

IDP Groups 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 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

3. How frequent are user provisioned via SCIM?

User/Group provisioning is done on a fixed Hard-Coded interval of 40-45 Minutes. If you need to provision a user/group immediately you can do so by clicking on Provision on demand within the provisioning Overview panel in Azure AD.


4. Error AADSTS650056: Misconfigured application, How do I resolve it? 


AADSTS650056: Misconfigured application. This could be due to one of the following: the client 
has not listed any permissions for 'AAD Graph' in the  requested permissions in the client's application 
registration. Or, the admin  has not consented in the tenant. Or, check the application identifier in the 
request  to ensure it matches the configured client application identifier. Or, check the certificate  in 
the request to ensure it's valid. Please contact your admin to fix the

If you are receiving the error message above, it means that either:

  • You may encounter an error if you don't have Global Admin rights to the Azure tenant where you are integrating. Please review the requirements at the start of the guide to resolve this issue.

  • Double-check your configuration on step 2.4 to ensure that you have inputted the correct values:
    • Identifier (Entity ID) = https://github.com/enterprises/Your_Enterprise_Name
    • Reply URL = https://github.com/enterprises/Your_Enterprise_Name/saml/consume
    • Sign on URL = https://github.com/enterprises/Your_Enterprise_Name/sso

  • At a GitHub level, you are not using the correct URLs under Single Sign-On. Please revisit in the guide Step 5.2 to ensure you are mapping the values correctly.
    • Sign on URL = Login URL (on Azure)
    • Issuer = Azure AD Identifier (on Azure)
    • Public Certificate = Base64 Certificate (on Azure)

5. Why can't I edit or change my IDP configuration and what would happen if I disable it?

As a Single sign-on enterprise owner, accessing your enterprise admin panel you have full control over your GitHub Enterprise tenant. However, when it comes to your identity provider configuration your options are limited as an enterprise owner. You will be able to change the public certificate in case you need to but you will not be able to change your Sign on URL , Issuer or disable SAML single sign-On.For you to be able to accomplish this you will need to login with your Enterprise's provided setup user account also know as the default initial admin account. This is because in order for you to change the Sign-on URL or Issuer you will need to disable SAML first. Disabling SAML will have a significant impact in your Enterprise. Details of the impact can be found within the following documentation:

You can disable SAML or OIDC single sign-on (SSO) and SCIM provisioning for Enterprise Managed Users by using a recovery code to sign in as the setup user.

6. I'm unable to integrate Azure AD SSO I keep on getting errors

Please reach out to our support team at GitHub Enterprise Support and provide them with:

  • Screenshot of the issue or error message.
  • Screenshot of your Azure AD 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.




Trademark Disclaimer

  • Microsoft products and services—including images, text, and software downloads (the "content")—are owned either by Microsoft Corporation or by third parties who have granted Microsoft permission to use the content. Microsoft cannot grant you permission for content that is owned by third parties. You may only copy, modify, distribute, display, license, or sell the content if you are granted explicit permission within the End-User License Agreement (EULA) or License Terms that accompany the content or are provided in the following guidelines. See Microsoft's Trademark Usage Guidelines for further policy details.

  • GITHUB®, the GITHUB® logo design, the INVERTOCAT logo design, OCTOCAT®, and the OCTOCAT® logo design are trademarks of GitHub, Inc., registered in the United States and other countries. The OCTOCAT design is the exclusive property of GitHub, Inc and has been federally registered with the United States Copyright Office. All rights reserved. See GitHub's Terms of Service for its Intellectual Property