Edit

Tutorial: Azure Active Directory single sign-on (SSO) integration with GitHub Enterprise Managed User

  • Article
  • 5 minutes to read

In this tutorial, you'll learn how to integrate GitHub Enterprise Managed User (EMU) with Azure Active Directory (Azure AD). When you integrate GitHub Enterprise Managed User with Azure AD, you can:

  • Control in Azure AD who has access to GitHub Enterprise Managed User.
  • Enable your users to be automatically signed-in to GitHub Enterprise Managed User with their Azure AD accounts.
  • Manage your accounts in one central location - the Azure portal.

Note

GitHub Enterprise Managed Users is a feature of GitHub Enterprise Cloud which is different from GitHub Enterprise's standard SAML SSO implementation. If you haven't specifically requested EMU instance, you have standard GitHub Enterprise Cloud plan. In that case, please refer to relevant documentation to configure your non-EMU organisation or enterprise account to authenticate with Azure Active Directory.

Prerequisites

To get started, you need the following items:

  • An Azure AD subscription. If you don't have a subscription, you can get a free account.
  • GitHub Enterprise Managed User single sign-on (SSO) enabled subscription.

Scenario description

In this tutorial, you configure and test Azure AD SSO in a test environment.

  • GitHub Enterprise Managed User supports SP and IDP initiated SSO.
  • GitHub Enterprise Managed User requires Automated user provisioning.

To configure the integration of GitHub Enterprise Managed User into Azure AD, you need to add GitHub Enterprise Managed User from the gallery to your list of managed SaaS apps.

  1. Sign in to the Azure portal using either a work or school account, or a personal Microsoft account.
  2. On the left navigation pane, select the Azure Active Directory service.
  3. Navigate to Enterprise Applications.
  4. To add new application, select New application.
  5. Type GitHub Enterprise Managed User in the search box.
  6. Select GitHub Enterprise Managed User from results panel and then click on the Create button. Wait a few seconds while the app is added to your tenant.

Alternatively, you can also use the Enterprise App Configuration Wizard. In this wizard, you can add an application to your tenant, add users/groups to the app, assign roles, as well as walk through the SSO configuration as well. Learn more about Microsoft 365 wizards.

Configure and test Azure AD SSO for GitHub Enterprise Managed User

To configure and test Azure AD SSO with GitHub Enterprise Managed User, perform the following steps:

  1. Configure Azure AD SSO - to enable SAML Single Sign On in your AAD tenant.
  2. Configure GitHub Enterprise Managed User SSO - to configure the single sign-on settings in your GitHub Enterprise.

Configure Azure AD SSO

Follow these steps to enable Azure AD SSO in the Azure portal.

  1. In the Azure portal, on the GitHub Enterprise Managed User application integration page, find the Manage section and select single sign-on.

  2. On the Select a single sign-on method page, select SAML.

  3. On the Set up single sign-on with SAML page, click the pencil icon for Basic SAML Configuration to edit the settings.

    Edit Basic SAML Configuration

  4. Ensure that you have your Enterprise URL before you begin. The ENTITY field mentioned below is the Enterprise name of your EMU-enabled Enterprise URL. For example, https://github.com/enterprises/contoso - contoso is the ENTITY. On the Basic SAML Configuration section, if you wish to configure the application in IDP initiated mode, enter the values for the following fields:

    a. In the Identifier text box, type a URL using the following pattern: https://github.com/enterprises/<ENTITY>

    Note

    Note the identifier format is different from the application's suggested format - please follow the format above. In addition, please ensure the **Identifier does not contain a trailing slash.

    b. In the Reply URL text box, type a URL using the following pattern: https://github.com/enterprises/<ENTITY>/saml/consume

  5. Click Set additional URLs and perform the following step if you wish to configure the application in SP initiated mode:

    In the Sign-on URL text box, type a URL using the following pattern: https://github.com/enterprises/<ENTITY>/sso

  6. On the Set up single sign-on with SAML page, in the SAML Signing Certificate section, find Certificate (Base64) and select Download to download the certificate and save it on your computer.

    The Certificate download link

  7. On the Set up GitHub Enterprise Managed User section, copy the URLs below and save it for configuring GitHub below.

    Copy configuration URLs

Assign the Azure AD test user

In this section, you'll assign your account to GitHub Enterprise Managed User in order to complete SSO setup.

  1. In the Azure portal, select Enterprise Applications, and then select All applications.
  2. In the applications list, select GitHub Enterprise Managed User.
  3. In the app's overview page, find the Manage section and select Users and groups.
  4. Select Add user, then select Users and groups in the Add Assignment dialog.
  5. In the Users and groups dialog, select your account from the Users list, then click the Select button at the bottom of the screen.
  6. In the Select a role dialog, select the Enterprise Owner role, then click the Select button at the bottom of the screen. Your account is assigned as an Enterprise Owner for your GitHub instance when you provision your account in the next tutorial.
  7. In the Add Assignment dialog, click the Assign button.

Configure GitHub Enterprise Managed User SSO

To configure single sign-on on GitHub Enterprise Managed User side, you will require the following items:

  1. The URLs from your AAD Enterprise Managed User Application above: Login URL; Azure AD Identifier; and Logout URL
  2. The account name and password for the first administrator user of your GitHub Enterprise. The credentials are provided by a password reset email from your GitHub Solutions Engineering contact.

Enable GitHub Enterprise Managed User SAML SSO

In this section, you'll take the information provided from AAD above and enter them into your Enterprise settings to enable SSO support.

  1. Go to https://github.com
  2. Click on Sign In at the top-right corner
  3. Enter the credentials for the first administrator user account. The login handle should be in the format: <your enterprise short code>_admin
  4. Navigate to https://github.com/enterprises/ <your enterprise name>. This information should be provided by your Solutions Engineering contact.
  5. On the navigation menu on the left, select Settings, then Authentication security.
  6. Click on the checkbox Require SAML authentication
  7. Enter the Sign-on URL. This URL is the Login URL that you copied from AAD above.
  8. Enter the Issuer. This URL is the Azure AD Identifier that you copied from AAD above.
  9. Enter the Public Certificate. Please open the base64 certificate that you downloaded above and paste the text contents of that file into this dialog.
  10. Click on Test SAML configuration. This will open up a dialog for you to log in with your Azure AD credentials to validate that SAML SSO is configured correctly. Log in with your AAD credentials. you will receive a message Passed: Successfully authenticated your SAML SSO identity upon successful validation.
  11. Click Save to persist these settings.
  12. Please save (download, print, or copy) the recovery codes in a secure place.
  13. Click on Enable SAML authentication.
  14. At this point, only accounts with SSO are able to log into your Enterprise. Follow the instructions in the document below on provisioning in order to provision accounts backed by SSO.

Next steps

GitHub Enterprise Managed User requires all accounts to be created through automatic user provisioning, you can find more details here on how to configure automatic user provisioning.