SAML SSO for GitLab.com groups

原文：https://docs.gitlab.com/ee/user/group/saml_sso/

• Configuring your Identity Provider
  • NameID
    • NameID Format
  • Metadata configuration
• Configuring GitLab
  • SSO enforcement
• Providers
  • Azure setup notes
  • Okta setup notes
  • OneLogin setup notes
  • Additional providers and setup options
• User access and management
  • Linking SAML to your existing GitLab.com account
  • Signing in to GitLab.com with SAML
  • Role
  • Blocking access
  • Unlinking accounts
• Glossary
• Configuring on a self-managed GitLab instance
  • Limitations
  • Omnibus installations
  • Source installations
• Troubleshooting
  • SAML debugging tools
  • Verifying configuration
  • Verifying NameID
  • Message: “SAML authentication failed: Extern uid has already been taken”
  • Message: “SAML authentication failed: User has already been taken”
  • Message: “SAML authentication failed: Email has already been taken”
  • Message: “SAML authentication failed: Extern uid has already been taken, User has already been taken”
  • Message: “Request to link SAML account must be authorized”
  • Stuck in a login “loop”
  • The NameID has changed
  • I need to change my SAML app
  • 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 身份提供商进行登录. 如果用户还不是成员，则登录过程会自动将用户添加到适当的组.

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

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

Configuring your Identity Provider

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

NameID

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

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

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

警告：用户使用 SSO SAML 设置登录到 GitLab 后，更改NameID将破坏配置，并有可能将用户锁定在 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.8 中引入 .
• 在 GitLab 11.11 中进行了改进 ，并在 GitLab UI 中不断实施.

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

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

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

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

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

Providers

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

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

Azure setup notes

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

我们推荐：

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

Okta setup notes

有关 Okta SAML 设置（包括 SCIM）的演示 ，请参见演示：Okta Group 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
• G Suite
• JumpCloud
• PingOne by Ping Identity

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

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

User access and management

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

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

• SCIM.
• 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或直接访问链接来登录 GitLab.com . 如果强制 SSO选项已打开，您将被重定向到通过身份提供者登录.

Signing in to GitLab.com with SAML

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

Role

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

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

Blocking access

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

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

Unlinking accounts

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

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

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

Glossary

Configuring on a self-managed GitLab instance

对于自我管理的 GitLab 实例，我们强烈建议改用实例范围的 SAML OmniAuth Provider .

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

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

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

Limitations

与建议的实例范围的 SAML相比，自管理实例上的组 SAML 受到限制. 推荐的解决方案使您可以利用：

• LDAP compatibility.
• LDAP Group Sync.
• Required groups.
• Admin groups.
• Auditor groups.

Omnibus installations

1. 确保为 GitLab 配置了 HTTPS .

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

   gitlab_rails['omniauth_enabled'] = true
   gitlab_rails['omniauth_providers'] = [{ name: 'group_saml' }]

Source installations

1. 确保为 GitLab 配置了 HTTPS .

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

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

Troubleshooting

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

SAML debugging tools

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

• SAML tracer for Firefox
• Chrome SAML Panel

应特别注意：

• NameID （我们用来标识正在登录的用户）.如果该用户先前已登录，则该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 是否已链接到该用户.

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

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

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

此错误表明您已以 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 大写字母与该用户的先前值不完全匹配.

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

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

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

Stuck in a login “loop”

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

另外，当用户需要将 SAML 链接到其现有的 GitLab.com 帐户时 ，请提供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 的更详细的文档 . GitLab.com 的 SAML 配置与自我管理实例的 SAML 配置基本相同. 但是，自我管理的 GitLab 实例使用支持更多选项的配置文件，如外部OmniAuth SAML 文档中所述 . 在内部使用ruby-saml库 ，因此我们有时在此处检查以验证不常用选项的低级详细信息.

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