Skip to main content

外部身份验证的用户名注意事项

当你使用 Enterprise Managed Users,GitHub Enterprise Cloud 遵循某些规则来确定企业中。

注意:本文仅适用于 Enterprise Managed Users。 如果使用 GitHub Enterprise Cloud 而不使用 Enterprise Managed Users,则用户名由用户创建,而不是由 GitHub 创建。

关于使用外部身份验证的用户名

如果使用具有 Enterprise Managed Users 的企业,则企业成员将通过 SAML 标识提供者 (IdP) 进行身份验证以访问 GitHub。 有关详细信息,请参阅“关于 Enterprise Managed Users”和“关于身份和访问管理”。

GitHub 通过规范 IdP 提供的标识符,然后添加下划线和短代码,从而在通过 SCIM 预配用户帐户时自动为每个用户创建用户名。 如果将多个标识符规范化为相同的用户名,则会发生用户名冲突,并且将仅创建第一个用户帐户。 可以通过更改 IdP 来解决用户名问题,以便规范化的用户名是唯一的并且符合 39 个字符的限制。

注意:由于 GitHub 在创建每个用户名时向 IdP 提供的规范化标识符添加下划线和短代码,因此冲突只会在每个 具有托管用户的企业 内发生。 托管用户帐户 可以与企业外部 GitHub.com 上的其他用户帐户共享 IdP 标识符或电子邮件地址。

关于 托管用户帐户 的用户名

创建 具有托管用户的企业 后,需要选择一个短代码作为企业成员用户名的后缀。 短代码必须是企业唯一的,长度为 3 ~ 8 个字符,由字母和数字组成,不包含特殊字符。配置 SAML SSO 的设置用户的用户名格式为 @SHORT-CODE_admin

通过标识提供者预配新用户时,新的 托管用户帐户 将有一个 GitHub 用户名,格式为 @IDP-USERNAME_SHORT-CODE 。 IDP-USERNAME 组件是通过规范从 IdP 发送的 SCIM userName 特性值而形成的。

标识提供者GitHub 用户名
Microsoft Entra ID(以前称为 Azure AD)IDP-USERNAME 是通过规范 UPN(用户主体名称)中 @ 字符之前的字符而形成的,不包括来宾帐户的 #EXT#
OktaIDP-USERNAME 是 IdP 提供的规范化用户名属性。

这些规则可能会导致 IdP 为多个用户提供相同的 IDP-USERNAME。 例如,对于 Entra ID,以下 UPN 将产生相同的用户名:

  • bob@contoso.com
  • bob@fabrikam.com
  • bob#EXT#fabrikamcom@contoso.com
  • bob_example#EXT#fabrikamcom@contoso.com
  • bob_example.com#EXT#fabrikamcom@contoso.com

这将导致用户名冲突,并且只会预配第一个用户。 有关详细信息,请参阅“解决用户名问题”。

用户名,包括下划线和短代码,不得超过 39 个字符。

关于用户名规范化

GitHub.com 上的用户帐户的用户名只能包含字母数字字符和短划线 (-)。

配置 SAML 身份验证时,GitHub Enterprise Cloud 使用从 IdP 发送的 SCIM userName 特性值来确定 GitHub.com 上相应用户帐户的用户名。 如果此值包含不受支持的字符,GitHub Enterprise Cloud 将按照以下规则规范化用户名。

  1. GitHub Enterprise Cloud 会将帐户用户名中的所有非字母数字字符规范化为短划线。 例如,用户名 mona.the.octocat 将规范化为 mona-the-octocat。 请注意,标准化的用户名也不能以短划线开头或结尾。 它们还不能包含两个连续的短划线。

  2. 创建自电子邮件地址的用户名使用 @ 字符前面的规范化字符创建。

  3. 从域帐户创建的用户名是从 \\ 分隔符后面的规范化字符创建的。

  4. 如果将多个帐户规范化为相同的 GitHub Enterprise Cloud 用户名,则将仅创建第一个用户帐户。 使用相同用户名的后续用户无法登录。 有关详细信息,请参阅“解决用户名问题”。

用户名规范化示例

提供程序上的标识符GitHub 上的规范化用户名结果
The.Octocatthe-octocat_SHORT-CODE此用户名已成功创建。
!The.Octocat-the-octocat_SHORT-CODE此用户名无法创建,因其以短划线开头。
The.Octocat!the-octocat-_SHORT-CODE此用户名无法创建,因其以短划线结尾。
The!!Octocatthe--octocat_SHORT-CODE此用户名无法创建,因其包含两个连续的短划线。
The!Octocatthe-octocat_SHORT-CODE此用户名无法创建。 虽然标准化的用户名有效,但它已经存在。
The.Octocat@example.comthe-octocat_SHORT-CODE此用户名无法创建。 虽然标准化的用户名有效,但它已经存在。
internal\\The.Octocatthe-octocat_SHORT-CODE此用户名无法创建。 虽然标准化的用户名有效,但它已经存在。
mona.lisa.the.octocat.from.github.united.states@example.commona-lisa-the-octocat-from-github-united-states_SHORT-CODE不会创建此用户名,因为它超出了 39 个字符的限制。

解决用户名问题

预配新用户时,如果用户名的长度超过 39 个字符(包含下划线和短代码),或者与企业中的现有用户冲突,则预配尝试将失败并出现 409 错误。

若要解决此问题,必须在 IdP 中进行以下任一更改,以便所有规范化的用户名都将符合字符限制并且是唯一的。

  • 更改导致问题的单个用户的 userName 特性值
  • 更改所有用户的 userName 特性映射
  • 配置所有用户的自定义 userName 特性

更改特性映射时,现有 托管用户帐户 的用户名将更新,但有关帐户的其他任何内容都不会更改,包括活动历史记录。

注意:GitHub 支持 无法为自定义特性映射或配置自定义表达式提供帮助。 如有任何问题,可以联系 IdP。

解决 Entra ID 的用户名问题

要解决 Entra ID 中的用户名问题,请修改冲突用户的用户主体名称值或修改 userName 属性的属性映射。 如果修改特性映射,可以选择现有特性或使用表达式来确保所有预配的用户都具有唯一的规范化别名。

  1. 在 Entra ID 中,打开 GitHub Enterprise Managed User 应用程序。
  2. 在左侧边栏中,单击“预配”。
  3. 单击“编辑预配”。
  4. 展开“映射”,然后单击“预配 Entra ID 用户”
  5. 单击 GitHub userName 特性映射。
  6. 更改特性映射。
    • 要将 Entra ID 中的现有属性映射到 GitHub 中的 userName 属性,请单击所需的属性字段。 然后,保存并等待,预配周期将在大约 40 分钟内发生。
    • 若要使用表达式而不是现有特性,请将映射类型更改为“表达式”,然后添加自定义表达式,使该值对所有用户都是唯一的。 例如,可以使用 [FIRST NAME]-[LAST NAME]-[EMPLOYEE ID]。 有关详细信息,请参阅 Microsoft Learn 上的有关在 Microsoft Entra ID 中编写属性映射表达式的参考

解决 Okta 的用户名问题

若要解决 Okta 中的用户名问题,请更新 GitHub Enterprise Managed User 应用程序的特性映射设置。

  1. 在 Okta 中,打开 GitHub Enterprise Managed User 应用程序。
  2. 单击“登录”。
  3. 在“设置”部分,单击“编辑”。
  4. 更新“应用程序用户名格式”。