SAML SSO for GitLab.com groups

• • NameID
  • Metadata configuration
• • SSO enforcement
• • Azure setup notes
  • Additional providers and setup options
• • Linking SAML to your existing GitLab.com account
  • Role
  • Unlinking accounts
• Configuring on a self-managed GitLab instance
  • Omnibus installations
• Troubleshooting
  • Verifying configuration
  • Message: “SAML authentication failed: Extern uid has already been taken”
  • Message: “SAML authentication failed: Email has already been taken”
  • Message: “Request to link SAML account must be authorized”
  • The NameID has changed
  • I need additional information to configure my identity provider

SAML SSO for GitLab.com groups

在 GitLab 11.0 中引入.

此页面描述了组的 SAML. 有关自我管理的 GitLab 实例上的实例范围内的 SAML，请参阅SAML OmniAuth Provider .

GitLab.com 上的 SAML 允许用户通过其 SAML 身份提供商进行登录. 如果用户还不是成员，则登录过程会自动将用户添加到适当的组.

如果您遵循我们的指导以使用或组管理的帐户自动执行用户配置，则无需手动创建此类帐户.

通过支持 SAML SSO 组的用户同步. SCIM 支持在 GitLab 组中添加和删除用户. 例如，如果您从 SCIM 应用程序中删除用户，则 SCIM 将从 GitLab 组中删除该用户.

1. 导航到该组，然后单击设置> SAML SSO .
2. 使用Assertion 使用者服务 URL ， Identifier和GitLab 单一登录 URL来配置 SAML 服务器. 另外，GitLab 还提供元数据 XML 配置 . 有关更多详细信息，请参见 .
3. 配置 SAML 响应以包括唯一标识每个用户的 NameID.
4. 如果使用组托管帐户，请配置 .
5. 设置身份提供者后，继续配置 GitLab .

GitLab.com 使用 SAML NameID 来识别用户. NameID 元素：

• 是 SAML 响应中的必填字段.
• 每个用户必须唯一.
• 必须是永久不变的值，例如随机生成的唯一用户 ID.
• 区分大小写. NameID 必须在随后的登录尝试中完全匹配，因此不应依赖可能在大小写之间变化的用户输入.
• 不应是电子邮件地址或用户名. 我们强烈建议您反对这些，因为很难保证它们永远不会改变，例如当一个人的名字改变时. 电子邮件地址也不区分大小写，这可能导致用户无法登录.

支持的提供程序的相关字段名称和建议值在提供程序特定的注释中 . 适当的相应字段.

警告：用户使用 SSO SAML 设置登录到 GitLab 后，更改将破坏配置，并有可能将用户锁定在 GitLab 组之外.

NameID Format

我们建议将 NameID 格式设置为Persistent除非使用要求其他格式的字段（例如电子邮件）.

Metadata configuration

GitLab 提供了可用于配置身份提供者的元数据 XML.

1. 导航到该组，然后单击设置> SAML SSO .
2. 复制提供的GitLab 元数据 URL .
3. 请遵循身份提供者的文档，并在请求时粘贴元数据 URL.

Configuring GitLab

设置好身份提供程序以与 GitLab 一起使用后，您需要配置 GitLab 以使用它进行身份验证：

1. 导航到组的“设置”>” SAML SSO” .
2. 从您的身份提供者中找到 SSO URL，然后在身份提供者单点登录 URL字段中输入 SSO URL.
3. 在” 证书”字段中找到并输入 SAML 令牌签名证书的指纹.
4. 单击” 为此组启用 SAML 身份验证”切换开关.
5. 点击保存更改按钮.

注意：请注意，证书必须在 SHA1 中. 配置身份提供者时，请使用安全签名算法.

SSO enforcement

• 在 GitLab 11.11 中进行了 ，并在 GitLab UI 中不断实施.

启用此选项后，用户必须浏览您组的 GitLab 单一登录 URL. 如果已配置，也可以通过 SCIM 添加它们. 无法手动添加用户，只能通过 UI 通过 SSO URL 登录来访问项目/组资源.

但是，每次访问时都不会提示用户通过 SSO 登录. GitLab 将检查用户是否已通过 SSO 进行身份验证，并且仅在会话过期时提示用户通过 SSO 登录.

我们打算为Git 和 API 活动添加类似的 SSO 要求.

为组启用 SSO 强制后，即使分叉了项目，用户也无法在顶级组之外的组中共享项目.

要禁止用户在顶级组之外进行贡献，请参阅” .

注意： GitLab 无法为未在此处列出的 IdP 提供支持.

在配置标识提供程序时 ，请考虑以下有关特定提供程序的注意事项，以帮助避免常见问题，并作为所用术语的指南.

Azure setup notes

有关包括 SCIM 在内的 Azure SAML 设置的演示，请参阅《 使用针对组的 SAML SSO 的 Azure 上的 SCIM 置备》演示 .

• 唯一用户标识符（名称标识符）设置为user.objectID .
• nameid-format设置为持久.

Okta setup notes

有关 Okta SAML 设置（包括 SCIM）的演示 ，请参见 .

在 Okta 的” 单一登录 URL”字段下，选中” 将此用于收件人 URL 和目标 URL “选项.

我们推荐：

• 应用程序用户名 （NameID）设置为Custom user.getInternalProperty("id") .
• 名称 ID 格式设置为Persistent .

OneLogin setup notes

OneLogin 应用目录中列出的 GitLab 应用适用于自我管理的 GitLab 实例. 对于 GitLab.com，请使用通用 SAML 测试连接器，例如 SAML 测试连接器（高级）.

Recommended NameID value: OneLogin ID.

Additional providers and setup options

SAML 标准意味着广泛的身份提供者将与 GitLab 一起使用. 不幸的是，我们尚未验证与所有 SAML 提供程序的连接. 有关更多信息，请参见关于提供程序的 .

您的身份提供者可能具有相关的文档. 它可能是通用的 SAML 文档，也可能是专门针对 GitLab 的. 例子：

• Auth0
• JumpCloud

您的身份提供商可能需要其他配置，例如：

如果上面没有列出您需要的信息，则不妨查看的故障排除文档 .

User access and management

一旦配置并启用了 Group SSO，用户就可以通过身份提供商的仪表板访问 GitLab.com 组. 如果配置了SCIM ，请参阅 “ 用户访问和链接设置”部分 .

当用户尝试使用 Group SSO 登录时，他们将需要一个配置了以下内容之一的帐户：

• .
• Group-managed accounts.
• 一个 GitLab.com 帐户.

Linking SAML to your existing GitLab.com account

要将 SAML 链接到您现有的 GitLab.com 帐户：

1. 登录到您的 GitLab.com 帐户.
2. 找到并访问您要登录的组的GitLab 单一登录 URL . 群组管理员可以在群组的“设置”>” SAML SSO”页面上找到此内容. 如果配置了登录 URL，则用户可以从身份提供者连接到 GitLab 应用.
3. Click Authorize.
4. 如果出现提示，请在身份提供者上输入您的凭据.
5. 您将被重定向回 GitLab.com，现在应该可以访问该组了. 将来，您可以使用 SAML 登录到 GitLab.com.

在随后的访问中，您应该能够使用 SAML或直接访问链接来 . 如果强制 SSO选项已打开，您将被重定向到通过身份提供者登录.

Signing in to GitLab.com with SAML

1. 登录到您的身份提供商.
2. 从应用程序列表中，单击” GitLab.com”应用程序（名称由身份提供者的管理员设置）.
3. 您将登录到 GitLab.com，并重定向到该组.

首次登录时，GitLab 会将您添加到具有 Guest 角色的顶级父组中. 具有适当特权的现有成员可以提升该新用户.

如果用户已经是组的成员，则链接 SAML 身份不会更改其角色.

Blocking access

要取消对该组的访问，请按顺序执行以下步骤：

1. 从身份提供者上的用户数据存储中删除用户，或从特定应用程序上的用户列表中删除用户.
2. 从 GitLab.com 组中删除用户.

Unlinking accounts

用户可以从其个人资料页面取消链接组的 SAML. 在以下情况下这可能会有所帮助：

• 您不再希望某个群组能够登录 GitLab.com.
• 您的 SAML NameID 已更改，因此 GitLab 无法再找到您的用户.

例如，要取消链接MyOrg帐户，以下” 断开连接”按钮将在” 配置文件”>”帐户”下可用：

Configuring on a self-managed GitLab instance

对于自我管理的 GitLab 实例，我们强烈建议改用 .

如果您需要允许通过多个 SAML 身份提供者进行访问，Group SAML SSO 可以提供帮助，但是作为多租户解决方案，它不太适合您管理自己的 GitLab 实例的情况.

要改为继续配置 Group SAML SSO，您需要启用group_saml OmniAuth 提供程序. 这可以通过以下方式完成：

• gitlab.rb用于 GitLab Omnibus 安装 .
• gitlab/config/gitlab.yml for .

Limitations

• .
• LDAP Group Sync.
• .
• Admin groups.
• .

Omnibus installations

1. 确保为 GitLab .

2. 启用 OmniAuth 和group_saml在提供gitlab.rb ：

Source installations

1. 确保为 GitLab .

2. 在gitlab/config/gitlab.yml启用 OmniAuth 和提供程序：

    omniauth:
        enabled: true
        providers:
          - { name: 'group_saml' }

本节包含可能遇到的问题的可能解决方案.

SAML debugging tools

SAML 响应是 base64 编码的，因此我们建议使用以下浏览器插件即时对其进行解码：

• Chrome SAML Panel

应特别注意：

• （我们用来标识正在登录的用户）.如果该用户先前已登录，则该ID 必须与我们存储的值匹配 .
• X509Certificate的存在，我们需要使用它来验证响应签名.
• SubjectConfirmation和Conditions ，如果配置错误，可能会导致错误.

Verifying configuration

For convenience, we’ve included some example resources used by our Support Team. While they may help you verify the SAML app configuration, they are not guaranteed to reflect the current state of third-party products.

Verifying NameID

在对组 SAML 设置进行故障排除时，任何经过身份验证的用户都可以通过访问https://gitlab.com/api/v4/user并检查身份下的extern_uid来使用 API​​来验证 NameID GitLab 是否已链接到该用户.

同样，具有适当权限的角色的组成员可以使用来查看该组成员的组 SAML 身份信息.

然后可以通过使用SAML 调试工具解码消息，将其与身份提供者发送的进行比较. 我们要求这些匹配项以识别用户.

此错误表明您已以 GitLab 用户身份登录，但已将 SAML 身份链接到其他 GitLab 用户. 退出，然后尝试使用 SSO SAML 链接再次登录，该链接应使用链接的用户帐户将您登录到 GitLab.

如果您不希望通过 SAML 登录使用该 GitLab 用户，则可以取消 GitLab 帐户与该组的 SAML 的链接 .

Message: “SAML authentication failed: User has already been taken”

与您登录的用户已经将 SAML 链接到另一个身份. 以下是可能的原因和解决方案：

Message: “SAML authentication failed: Email has already been taken”

Message: “SAML authentication failed: Extern uid has already been taken, User has already been taken”

同时获得这两个错误表明，身份提供者提供的 NameID 大写字母与该用户的先前值不完全匹配.

可以通过配置返回一致的值来防止这种情况. 为单个用户解决此问题涉及取消 GitLab 帐户中的 SAML 链接 ，尽管这将导致组成员身份和 Todos 丢失.

Message: “Request to link SAML account must be authorized”

确保尝试链接其 GitLab 帐户的用户已添加为身份提供者的 SAML 应用中的用户.

Stuck in a login “loop”

确保在身份提供者的 SAML 应用中将GitLab 单一登录 URL配置为”登录 URL”（或类似命名的字段）.

另外，当用户需要 ，请提供GitLab 单一登录 URL，并指示用户不要在首次登录时使用 SAML 应用.

The NameID has changed

I need to change my SAML app

用户将需要取消链接当前的 SAML 身份 ， 到新的 SAML 应用.

I need additional information to configure my identity provider

提供商之间的许多 SAML 术语可能会有所不同. 您正在查找的信息可能以其他名称列出.

有关更多信息，请从您的身份提供商的文档开始. 查找他们的选项和示例，以了解他们如何配置 SAML. 这可以提供有关配置 GitLab 以便与这些提供程序一起使用所需的提示.

它也有助于查看我们 . GitLab.com 的 SAML 配置与自我管理实例的 SAML 配置基本相同. 但是，自我管理的 GitLab 实例使用支持更多选项的配置文件，如外部OmniAuth SAML 文档中所述 . 在内部使用 ，因此我们有时在此处检查以验证不常用选项的低级详细信息.

它还可以帮助将提供商的 XML 响应与我们用于内部测试的 XML 示例进行比较 .