Skip to main content

About Enterprise Managed Users

You can centrally manage identity and access for your enterprise members on GitHub from your identity provider (IdP).

About Enterprise Managed Users

With Enterprise Managed Users, you manage the lifecycle and authentication of your users on GitHub.com from an external identity management system, or IdP. You can provide access to GitHub Enterprise Cloud to people who have existing identities and group membership on your IdP. Your IdP provisions new user accounts with access to your enterprise on GitHub.com. You control usernames, profile data, team membership, and repository access for the user accounts from your IdP.

On your IdP, you can give each managed user account a role, such as member, enterprise owner, or guest collaborator. Managed user accounts can own organizations within your enterprise and can add other managed user accounts to the organizations and teams within. For more information, see "Roles in an enterprise" and "About organizations."

When your enterprise uses OIDC SSO, GitHub will automatically use your IdP's conditional access policy (CAP) IP conditions to validate user interactions with GitHub, when members change IP addresses, and each time a personal access token or SSH key is used. For more information, see "About support for your IdP's Conditional Access Policy."

You can grant managed user accounts access to and the ability to contribute to repositories within your enterprise, but managed user accounts cannot create public content or collaborate with other users, organizations, and enterprises on the rest of GitHub. For more information, see "Abilities and restrictions of managed user accounts."

The usernames of your enterprise's managed user accounts and their profile information, such as display names and email addresses, are set by through your IdP and cannot be changed by the users themselves. For more information, see "Usernames and profile information."

Enterprise owners can audit all of the managed user accounts' actions on GitHub. For more information, see "Audit log events for your enterprise."

To use Enterprise Managed Users, you need a separate type of enterprise account with Enterprise Managed Users enabled. For more information about creating this account, see "Getting started with Enterprise Managed Users."

Note: There are multiple options for identity and access management with GitHub Enterprise Cloud, and Enterprise Managed Users is not the best solution for every customer. For more information about whether Enterprise Managed Users is right for your enterprise, see "Identifying the best authentication method for your enterprise" and "Abilities and restrictions of managed user accounts."

About authentication and user provisioning

With Enterprise Managed Users, your IdP creates and updates user accounts on GitHub.com. Users must authenticate on your IdP to access your enterprise's resources on GitHub.com. GitHub Enterprise Cloud maintains a record of the external identity on your IdP that corresponds with the user account.

GitHub partners with some developers of identity management systems to provide a "paved-path" integration with Enterprise Managed Users. These IdPs mostly provide authentication using SAML. Microsoft Entra ID (previously known as Azure AD) also offers OIDC for authentication. The IdP applications provision users with System for Cross-domain Identity Management (SCIM).

Partner IdPSAMLOIDCSCIM
Entra ID
Okta
PingFederate

Other IdPs must adhere to the SAML 2.0 specification for authentication. You can configure provisioning with IdPs that adhere to GitHub's integration guidelines. The IdP must adhere to the SCIM 2.0 specification and communicate with GitHub's REST API. For example, the IdP could be a commercial identity management system that GitHub has not tested, or a custom identity system that your company builds.

Notes:

  • Support for provisioning users with GitHub's public SCIM schema is in private beta and subject to change. To request access to the beta, contact your account manager on GitHub's Sales team.
  • This operation allows you to provision user accounts for your enterprise on GitHub Enterprise Cloud using SCIM. The operation is only available for use with Enterprise Managed Users. If you don't use Enterprise Managed Users and want to provision access to your organizations using SCIM, see "REST API endpoints for SCIM."
  • GitHub recommends that you test provisioning in an environment that's isolated from the production data on your IdP and GitHub.com.

For more information about authentication and provisioning, see the following articles.

Some customers have reported success using a partner IdP's application only for authentication, in combination with a different IdP for provisioning. For example, a combination of Okta for authentication and a custom SCIM solution for provisioning, or a combination of Keycloak for authentication and SailPoint for provisioning. GitHub has not tested all IdPs, and does not test partner IdPs in combination with other IdPs.

For more information about provisioning users from your IdP using the private beta of GitHub's SCIM schema, see "Provisioning users with SCIM using the REST API," and consult your IdP's documentation, support team, or other resources.

After you initially configure authentication and provisioning, GitHub does not recommend migration to a different platform for authentication or provisioning. If you need to migrate an existing enterprise to a different platform for authentication or provisioning, contact your account manager on GitHub's Sales team.

Getting started with Enterprise Managed Users

Before your developers can use GitHub Enterprise Cloud with Enterprise Managed Users, you must follow a series of configuration steps.

  1. To use Enterprise Managed Users, you need a separate type of enterprise account with Enterprise Managed Users enabled. To try out Enterprise Managed Users or to discuss options for migrating from your existing enterprise, please contact GitHub's Sales team.

    Your contact on the GitHub Sales team will work with you to create your new enterprise with managed users. You'll need to provide the email address for the user who will set up your enterprise and a short code that will be used as the suffix for your enterprise members' usernames. The short code must be unique to your enterprise, a three-to-eight character alphanumeric string, and contain no special characters. For more information, see "Usernames and profile information."

  2. After we create your enterprise, you will receive an email from GitHub inviting you to choose a password for your enterprise's setup user, which will be the first owner in the enterprise. Use an incognito or private browsing window when setting the password and saving the recovery codes for the user. The setup user is only used to configure single sign-on and SCIM provisioning integration for the enterprise. It will no longer be allowed to access enterprise or organization settings once SSO is configured, unless an SSO recovery code is used.

    The setup user's username is your enterprise's shortcode suffixed with _admin, for example fabrikam_admin. If you need to sign in as the setup user later, you can enter the username and password at any login page. A link to the login page is also provided on the SSO page, for convenience.

    If you need to reset the password for your setup user, contact GitHub Support through the GitHub Support portal.

  3. After you log in as the setup user, we recommend enabling two-factor authentication. The setup user's password and two-factor credentials can also be used to enter sudo mode, which is required to take sensitive actions. For more information, see "Configuring two-factor authentication" and "Sudo mode."

  4. To get started, configure how your members will authenticate. If you are using Entra ID as your IdP, you can choose between OpenID Connect (OIDC) and Security Assertion Markup Language (SAML). We recommend OIDC, which includes support for Conditional Access Policies (CAP). If you require multiple enterprises with managed user accounts provisioned from one tenant, you must use SAML for each enterprise after the first. If you are using another IdP, like Okta or PingFederate, you can use SAML to authenticate your members.

    To get started, read the guide for your chosen authentication method.

  5. Once you have configured SSO, you can configure SCIM provisioning. SCIM is how your IdP will create managed user accounts on GitHub.com. For more information on configuring SCIM provisioning, see "Configuring SCIM provisioning for Enterprise Managed Users."

  6. Once authentication and provisioning are configured, you can start managing organization membership for your managed user accounts by synchronizing IdP groups with teams. For more information, see "Managing team memberships with identity provider groups."

If members of your enterprise must use one workstation to contribute to repositories on GitHub.com from both a managed user account and a personal account, you can provide support. For more information, see "Supporting developers with multiple user accounts on GitHub.com."

About organization membership management

Organization memberships can be managed manually, or you can update memberships automatically using IdP groups. To manage organization memberships through your IdP, the members must be added to an IdP group, and the IdP group must be connected to a team within the organization. For more information about managing organization and team memberships automatically, see "Managing team memberships with identity provider groups."

The way a member is added to an organization owned by your enterprise (through IdP groups or manually) determines how they must be removed from an organization.

  • If a member was added to an organization manually, you must remove them manually. Unassigning them from the GitHub Enterprise Managed User application on your IdP will suspend the user but not remove them from the organization.
  • If a user became a member of an organization because they were added to IdP groups mapped to one or more teams in the organization, removing them from all of the mapped IdP groups associated with the organization will remove them from the organization.

To discover how a member was added to an organization, you can filter the member list by type. For more information, see "Viewing people in your enterprise."

Authenticating with a managed user account

Managed user accounts must authenticate through your IdP. The way that managed user accounts authenticate depends on whether you configure SAML or OIDC authentication.

If your enterprise is configured for SAML authentication, a managed user account can access your enterprise by visiting their IdP application portal. If your enterprise is configured for OIDC authentication, a managed user account can access your enterprise by using the login page on GitHub.com. IdP-initiated authentication is not currently supported for OIDC. In either configuration, a managed user account can initiate authentication directly from the organization or enterprise's page on GitHub.com.

By default, when an unauthenticated user attempts to access an enterprise that uses Enterprise Managed Users, GitHub displays a 404 error. An enterprise owner can optionally enable automatic redirects to single sign-on (SSO) instead of the 404. For more information, see "Enforcing policies for security settings in your enterprise."

If a SAML configuration error or an issue with your identity provider (IdP) prevents you from using SAML SSO, you can use a recovery code to access your enterprise. For more information, see "Managing recovery codes for your enterprise."

Authenticating as a managed user account via GitHub.com

  1. Navigate to https://github.com/login.
  2. In the "Username or email address" text box, enter your username including the underscore and short code. When the form recognizes your username, the form will update. You do not need to enter your password on this form.
  3. To continue to your IdP, click Sign in with your identity provider.

Usernames and profile information

GitHub Enterprise Cloud automatically creates a username for each person by normalizing an identifier provided by your IdP. For more information, see "Username considerations for external authentication."

The profile name and email address of a managed user account is provided by the IdP. Managed user accounts cannot change their profile name or email address on GitHub, and the IdP can only provide a single email address. If you change the email address associated with a user in your IdP, this will delink the user from the contribution history associated with their old email address.

A conflict may occur when provisioning users if the unique parts of the identifier provided by your IdP are removed during normalization. If you're unable to provision a user due to a username conflict, you should modify the username provided by your IdP. For more information, see "Username considerations for external authentication."

Note: Because GitHub adds an underscore and short code to the normalized identifier provided by your IdP when creating each username, conflicts can only occur within each enterprise with managed users. Managed user accounts can share IdP identifiers or email addresses with other user accounts on GitHub.com that are outside the enterprise.

Supporting developers with multiple user accounts on GitHub.com

People on your team may need to contribute to resources on GitHub.com that are outside of your enterprise with managed users. For example, you may wish to maintain a separate enterprise for your company's open source projects. Because a managed user account cannot contribute to public resources, users will need to maintain a separate, personal account for this work.

People who must contribute from two user accounts on GitHub.com using one workstation can configure Git to simplify the process. For more information, see "Managing multiple accounts."

If there are people on your team who do need to regularly switch between accounts on GitHub.com, such as their personal accounts and one or more managed user accounts, it's possible to sign in to multiple accounts and quickly switch between them without always needing to reauthenticate. For more information, see "Switching between accounts."