Skip to main content

Username considerations for external authentication

When you use Enterprise Managed Users, GitHub Enterprise Cloud follows certain rules to determine the username for each user account in your enterprise.

Note: This article only applies to Enterprise Managed Users. If you use GitHub Enterprise Cloud without Enterprise Managed Users, usernames are created by users, not GitHub.

About usernames with external authentication

If you use an enterprise with Enterprise Managed Users, members of your enterprise authenticate to access GitHub through your SAML identity provider (IdP). For more information, see "About Enterprise Managed Users" and "About authentication for your enterprise."

GitHub Enterprise Cloud automatically creates a username for each person when their user account is provisioned via SCIM, by normalizing an identifier provided by your IdP. If multiple identifiers are normalized into the same username, a username conflict occurs, and only the first user account is created. You can resolve username conflicts by making a change in your IdP so that the normalized usernames will be unique.

About usernames for managed userアカウント

When your managed usersを持つEnterprise is created, you will choose 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. The setup user who configures SAML SSO has a username in the format of @SHORT-CODE_admin.

When you provision a new user from your identity provider, the new 管理されているユーザアカウント will have a GitHub username in the format of @IDP-USERNAME_SHORT-CODE. The IDP-USERNAME component is formed by normalizing the SCIM userName attribute value sent from the IdP.

Identity providerGitHub username
Azure Active Directory (Azure AD)IDP-USERNAME is formed by normalizing the characters preceding the @ character in the UPN (User Principal Name), which does not include the #EXT# for guest accounts.
OktaIDP-USERNAME is the normalized username attribute provided by the IdP.

These rules may result in your IdP providing the same IDP-USERNAME for multiple users. For example, for Azure AD, the following UPNs will result in the same username:


This will cause a username conflict, and only the first user will be provisioned. For more information, see "Resolving username conflicts."

Usernames, including underscore and short code, must not exceed 39 characters.

About username normalization

Usernames for user accounts on can only contain alphanumeric characters and dashes (-).

When you configure SAML authentication, GitHub Enterprise Cloud uses the SCIM userName attribute value sent from the IdP to determine the username for the corresponding user account on If this value includes unsupported characters, GitHub Enterprise Cloud will normalize the username per the following rules.

  1. GitHub Enterprise Cloudは、アカウントのユーザ名に含まれている非英数字をダッシュに変換します。 For example, a username of mona.the.octocat will be normalized to mona-the-octocat. 変換されたユーザ名の先頭及び末尾はダッシュであってはならないことに注意してください。 2つの連続するダッシュを含めることもできません。

  2. メールアドレスから作成されたユーザ名は、@以前の文字を変換して作成されます。

  3. 複数のアカウントが変換後に同じGitHub Enterprise Cloudのユーザ名になる場合、最初のユーザアカウントだけが作成されます。 同じユーザ名のそれ以降のユーザは、サインインできません。 For more information, see "Resolving username conflicts."

Examples of username normalization

Identifier on providerNormalized username on GitHub結果
The!Octocatthe-octocat_SHORT-CODEこのユーザ名は作成されません。 変換されたユーザ名は正当ですが、すでに存在しています。
The.Octocat@example.comthe-octocat_SHORT-CODEこのユーザ名は作成されません。 変換されたユーザ名は正当ですが、すでに存在しています。
mona.lisa.the.octocat.from.github.united.states@example.commona-lisa-the-octocat-from-github-united-states_SHORT-CODEThis username is not created, because it exceeds the 39-character limit.

Resolving username conflicts

When a new user is being provisioned, if the user's normalized username conflicts with an existing user in the enterprise, the provisioning attempt will fail with a 409 error.

To resolve this problem, you must make a change in your IdP so that the normalized usernames will be unique. If you cannot change the identifier that's being normalized, you can change the attribute mapping for the userName attribute. If you change the attribute mapping, usernames of existing managed userアカウント will be updated, but nothing else about the accounts will change, including activity history.

Note: GitHub Support cannot provide assistance with customizing attribute mappings or configuring custom expressions. You can contact your IdP with any questions.

Resolving username conflicts with Azure AD

To resolve username conflicts in Azure AD, either modify the User Principal Name value for the conflicting user or modify the attribute mapping for the userName attribute. If you modify the attribute mapping, you can choose an existing attribute or use an expression to ensure that all provisioned users have a unique normalized alias.

  1. In Azure AD, open the GitHub Enterprise Managed User application.
  2. In the left sidebar, click Provisioning.
  3. Click Edit Provisioning.
  4. Expand Mappings, then click Provision Azure Active Directory Users.
  5. Click the GitHub userName attribute mapping.
  6. Change the attribute mapping.
    • To map an existing attribute in Azure AD to the userName attribute in GitHub, click your desired attribute field. Then, save and wait for a provisioning cycle to occur within about 40 minutes.
    • To use an expression instead of an existing attribute, change the Mapping type to "Expression", then add a custom expression that will make this value unique for all users. For example, you could use [FIRST NAME]-[LAST NAME]-[EMPLOYEE ID]. For more information, see Reference for writing expressions for attribute mappings in Azure Active Directory in Microsoft Docs.

Resolving username conflicts with Okta

To resolve username conflicts in Okta, update the attribute mapping settings for the GitHub Enterprise Managed User application.

  1. In Okta, open the GitHub Enterprise Managed User application.
  2. Click Sign On.
  3. In the "Settings" section, click Edit.
  4. Update the "Application username format."