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.
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.
When your enterprise with managed users 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 managed user account 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 provider||GitHub username|
|Azure Active Directory (Azure AD)||IDP-USERNAME is formed by normalizing the characters preceding the |
|Okta||IDP-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.
Usernames for user accounts on GitHub.com 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 GitHub.com. If this value includes unsupported characters, GitHub Enterprise Cloud will normalize the username per the following rules.
GitHub Enterprise Cloud will normalize any non-alphanumeric character in your account's username into a dash. For example, a username of
mona.the.octocatwill be normalized to
mona-the-octocat. Note that normalized usernames also can't start or end with a dash. They also can't contain two consecutive dashes.
Usernames created from email addresses are created from the normalized characters that precede the
If multiple accounts are normalized into the same GitHub Enterprise Cloud username, only the first user account is created. Subsequent users with the same username won't be able to sign in. For more information, see "Resolving username conflicts."
|Identifier on provider||Normalized username on GitHub||Result|
|The.Octocat||This username is created successfully.|
|!The.Octocat||This username is not created, because it starts with a dash.|
|The.Octocat!||This username is not created, because it ends with a dash.|
|The!!Octocat||This username is not created, because it contains two consecutive dashes.|
|The!Octocat||This username is not created. Although the normalized username is valid, it already exists.|
|This username is not created. Although the normalized username is valid, it already exists.|
|This username is not created, because it exceeds the 39-character limit.|
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
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 accounts 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.
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.
- In Azure AD, open the GitHub Enterprise Managed User application.
- In the left sidebar, click Provisioning.
- Click Edit Provisioning.
- Expand Mappings, then click Provision Azure Active Directory Users.
- Click the GitHub
- Change the attribute mapping.
- To map an existing attribute in Azure AD to the
userNameattribute 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.
- To map an existing attribute in Azure AD to the
To resolve username conflicts in Okta, update the attribute mapping settings for the GitHub Enterprise Managed User application.
- In Okta, open the GitHub Enterprise Managed User application.
- Click Sign On.
- In the "Settings" section, click Edit.
- Update the "Application username format."