SaaS 群组的 SAML SSO

用户可以通过其 SAML 身份提供商登录极狐GitLab。

SCIM 将用户与 SaaS 上的群组同步。

当您从 SCIM 应用程序添加或删除用户时，SCIM 会从极狐GitLab 群组添加或删除用户。
如果用户还不是群组成员，则会在登录过程中将用户添加到群组中。

您只能为顶级群组配置 SAML SSO。

设置您的身份提供商

由于 SAML 标准的存在，您可以在极狐GitLab 中使用各种身份提供商。您的身份提供商可能有相关文档，可能是通用的 SAML 文档，也可能是专门针对极狐GitLab 的文档。

设置身份提供商时，请使用以下提供商特定文档来帮助避免常见问题，并作为所用术语的指南。

对于未列出的身份提供商，您可以参阅有关配置身份提供商的实例 SAML 说明来获取更多指导。

极狐GitLab 提供以下信息仅供指导。如果您对配置 SAML 应用程序有任何疑问，请联系提供商的支持人员。

Azure

要使用 Azure 作为身份提供商来设置 SSO：

在左侧边栏中，选择 搜索或转到 并找到您的群组。
选择 设置 > SAML SSO。
请注意此页面上的信息。

转到 Azure 并遵循为应用程序配置 SSO 的说明。极狐GitLab 设置与 Azure 字段对应如下。

极狐GitLab 设置	Azure 字段
身份标识	Identifier (Entity ID)
断言消费者服务 URL	Reply URL (Assertion Consumer Service URL)
极狐GitLab 单点登录网址	Sign on URL
身份验证提供商单点登录 URL	Login URL
证书指纹	Thumbprint

您应该设置以下属性：
- 将 Unique User Identifier (Name identifier) 设置为 user.objectID。
- 将 nameid-format 设置为 persistent。有关更多信息，请参阅如何管理用户 SAML 身份。
- 将 Additional claims 设置为支持的属性。
确保身份提供商设置为由提供商发起的调用，关联现有的极狐GitLab 账户。
可选。如果您使用群组同步，请自定义群组声明的名称来匹配所需的属性。

Okta

要使用 Okta 作为身份提供商来设置 SSO：

在左侧边栏中，选择 搜索或转到 并找到您的群组。
选择 设置 > SAML SSO。
请注意此页面上的信息。

按照在 Okta 中设置 SAML 应用程序的说明进行操作。

极狐GitLab 与 Okta 字段的对应如下。

极狐GitLab 设置	Okta 字段
身份标识	Audience URI
断言消费者服务 URL	Single sign-on URL
极狐GitLab 单点登录网址	Login page URL（在 Application Login Page 设置下）
身份验证提供商单点登录 URL	Identity Provider Single Sign-On URL

在 Okta Single sign-on URL 字段下，选中 Use this for Recipient URL and Destination URL 复选框。
设置以下值：
- 对于 Application username (NameID)：自定义 user.getInternalProperty("id")。
- 对于 Name ID Format：Persistent。有关更多信息，请参阅管理用户 SAML 身份。
确保身份提供商设置为由提供商发起的调用，关联现有的极狐GitLab 账户。

应用程序目录中提供的 Okta GitLab 应用程序仅支持 SCIM。

使用元数据

要配置某些身份提供商，您需要极狐GitLab 元数据 URL。要查找此 URL：

在左侧边栏中，选择 搜索或转到 并找到您的群组。
选择 设置 > SAML SSO。
复制提供的 极狐GitLab 元数据 URL。
按照身份提供商的文档进行操作，并在需要时粘贴元数据 URL。

查看您的身份提供商的文档，了解它是否支持极狐GitLab 元数据 URL。

管理身份提供商

设置身份提供商后，您可以：

更改身份提供商。
更改电子邮件域名。

更改身份提供商

您可以更改为使用不同的身份提供商。在更改过程中，用户无法访问任何 SAML 群组。为了规避这种情况，您可以禁用强制 SSO。

要更改身份提供商：

使用新身份提供商配置群组。
可选。如果 NameID 不相同，请更改用户的 NameID。

更改电子邮件域名

要将用户迁移到新的电子邮件域名，请通知用户：

添加新电子邮件作为其账户的主要电子邮件并进行验证。
可选。从账户中删除他们的旧电子邮件。

如果 NameID 配置了电子邮件地址，请更改用户的 NameID。

配置极狐GitLab

设置身份提供商与极狐GitLab 配合使用后，您必须配置极狐GitLab，使用它进行身份验证：

在左侧边栏中，选择 搜索或转到 并找到您的群组。
选择 设置 > SAML SSO。
填写字段：
- 在 身份提供商单点登录 URL 字段中，输入来自您的身份提供商的 SSO URL。
- 在 证书指纹 字段中，输入 SAML 令牌签名证书的指纹。
在 默认成员角色 字段中，选择要分配给新用户的角色。默认角色是访客。在 13.10 及更高版本中，群组所有者可以设置除访客之外的默认成员角色。为此，为群组配置 SAML SSO。该角色成为添加到群组中的所有用户的起始角色。
选择 为此群组启用 SAML 身份验证 复选框。
可选。选择：
- 对该群组的 Web 活动强制执行仅 SSO 身份验证。
- 对该群组的 Git 活动强制执行仅 SSO 身份验证。有关详细信息，请参阅 SSO 强制执行文档。
选择 保存更改。

证书指纹算法必须采用 SHA1。配置身份提供商时，请使用安全签名算法。

用户访问和管理

配置并启用群组 SSO 后，用户可以通过身份提供商的仪表盘访问 SaaS 群组。

当用户尝试使用群组 SSO 登录时，极狐GitLab 会尝试根据以下内容查找或创建用户：

查找具有匹配 SAML 身份的现有用户。这意味着用户可能拥有由 SCIM 创建的账户，或者可能之前已使用该群组的 SAML IdP 登录。
如果没有具有相同电子邮件地址的冲突用户，则自动创建一个新账户。
如果存在具有相同电子邮件地址的冲突用户，则将用户重定向到登录页面：
- 使用另一个电子邮件地址创建一个新账户。
- 登录到其现有账户来关联 SAML 身份。

用户属性

您可以将用户信息作为 SAML 断言中的属性传递给极狐GitLab。

用户的电子邮件地址可能是 email 或 mail 属性。
用户名可能是 username 或 nickname 属性。您仅需指定其中之一。

有关更多信息，请参阅可用于私有化部署版极狐GitLab 实例的属性。

将 SAML 关联到您现有的 SaaS 账户

记住我 复选框引入于 15.7 版本。

要将 SAML 关联到您现有的 SaaS 账户：

登录您的 SaaS 账户。如有必要，重置您的密码。
找到并访问您要登录的群组的极狐GitLab 单点登录 URL。群组所有者可以在群组的 设置 > SAML SSO 页面上找到此信息。如果配置了登录 URL，用户可以从身份提供商连接到极狐GitLab 应用程序。
可选。选择 记住我 复选框可在 2 周内保持登录极狐GitLab 的状态。您可能仍会被要求更频繁地向 SAML 提供商重新进行身份验证。
选择授权。
如果出现提示，请在身份提供商上输入您的凭据。
然后您将被重定向回 SaaS，现在应该可以访问该群组。将来，您可以使用 SAML 登录 SaaS。

如果用户已经是该群组的成员，则关联 SAML 身份不会更改其角色。

在后续访问中，您应该能够使用 SAML 登录 SaaS 或直接访问链接。如果启用 强制 SSO 选项，您将被重定向来通过身份提供商登录。

使用 SAML 登录 SaaS

登录您的身份提供商。
从应用程序列表中，选择 SaaS 对应的应用程序（该名称由身份提供商的管理员设置）。
然后，您将登录 SaaS 并重定向到该群组。

管理用户 SAML 身份

使用 SAML API 更新 SAML 身份功能引入于 15.5 版本。

SaaS 使用 SAML NameID 来识别用户。NameID 是：

SAML 响应中的必填字段。
区分大小写。

NameID 必须：

每个用户都是独一无二的。
是一个永不改变的持久值，例如随机生成的唯一用户 ID。
与后续登录尝试完全匹配，因此不应依赖于可能在大小写之间变化的用户输入。

NameID 不应是电子邮件地址或用户名，因为：

电子邮件地址和用户名更有可能随着时间的推移而改变。例如，当一个人的名字改变时。
电子邮件地址不区分大小写，这可能会导致用户无法登录。

NameID 格式必须是 Persistent，除非您使用的字段（例如电子邮件）需要不同的格式。您可以使用除 Transient 之外的任何格式。

更改用户 NameID

群组所有者可以使用 SAML API 更改其群组成员的 NameID 并更新他们的 SAML 身份。

如果配置了 SCIM，群组所有者可以使用 SCIM API。

或者，要求用户重新连接其 SAML 账户。

要求相关用户取消其账户与群组的关联。
要求相关用户将他们的账户关联到新的 SAML 应用程序。

用户使用 SSO SAML 登录极狐GitLab 后，更改 NameID 值会破坏配置，并可能将用户锁定在极狐GitLab 群组之外。

有关特定身份提供商的建议值和格式的详细信息，请参阅设置您的身份提供商。

从 SAML 响应配置用户设置

引入于 13.7 版本。

极狐GitLab 允许根据 SAML 响应中的值设置某些用户属性。如果现有用户最初是由群组配置的，则该用户的属性将从 SAML 响应值进行更新。通过以下方式创建账户时，用户由群组配置：

通过 SCIM。
首次使用 SAML SSO 登录 SaaS 群组。

支持的用户属性

can_create_group - true 或 false 指示用户是否可以创建新群组。默认为 true。
projects_limit - 用户可以创建的个人项目总数。0 值表示用户无法在其个人命名空间中创建新项目。默认值为 10000。

SAML 响应示例

您可以在开发者工具或浏览器控制台中找到 Base64 编码格式的 SAML 响应。使用您选择的 base64 解码工具将信息转换为 XML。以下为 SAML 响应示例。

   <saml2:AttributeStatement>
      <saml2:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
         <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">user.email</saml2:AttributeValue>
      </saml2:Attribute>
      <saml2:Attribute Name="username" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
        <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">user.nickName</saml2:AttributeValue>
      </saml2:Attribute>
      <saml2:Attribute Name="first_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
         <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">user.firstName</saml2:AttributeValue>
      </saml2:Attribute>
      <saml2:Attribute Name="last_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
         <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">user.lastName</saml2:AttributeValue>
      </saml2:Attribute>
      <saml2:Attribute Name="can_create_group" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
         <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">true</saml2:AttributeValue>
      </saml2:Attribute>
      <saml2:Attribute Name="projects_limit" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
         <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">10</saml2:AttributeValue>
      </saml2:Attribute>
   </saml2:AttributeStatement>

使用经过验证的域名绕过用户电子邮件确认

引入于 15.4 版本。

默认情况下，配置有 SAML 或 SCIM 的用户会收到一封验证电子邮件来验证其身份。此外，您可以使用自定义域名配置极狐GitLab，极狐GitLab 会自动确认用户账户。用户仍然会收到企业用户欢迎电子邮件。符合以下条件的用户会绕过确认：

使用 SAML 或 SCIM 进行配置的用户。
拥有属于已验证域名的电子邮件地址的用户。

阻止用户访问

要在仅配置 SAML SSO 时撤销用户对群组的访问权限，请执行以下任一操作：

从以下位置（按顺序）删除用户：
1. 身份提供商上的用户数据存储或特定应用程序上的用户列表。
2. SaaS 群组。
在顶级群组使用群组同步，并将默认角色设置为最小访问权限，从而自动阻止其对群组中所有资源的访问。

取消关联账户

用户可以从其个人资料页面取消群组的 SAML 关联，特别适用于以下情况：

您不再希望某个群组能够让您登录 SaaS。
您的 SAML NameID 已更改，因此极狐GitLab 无法再找到您的用户。

取消关联账户会删除群组中分配给该用户的所有角色。如果用户重新关联其账户，则需要重新分配角色。

群组需要至少一名所有者。如果您的账户是该群组中的唯一所有者，则您无法取消该账户的关联。在这种情况下，请将另一个用户设置为群组所有者，然后您可以取消关联该账户。

例如，要取消关联 MyOrg 账户：

在左侧边栏中，选择您的头像。
选择 编辑个人资料。
在左侧边栏中，选择账户。
在 服务登录 部分中，选择已连接账户旁边的 断开连接。

强制 SSO

对于以下情况，在 SaaS 上强制执行 SSO：

当启用 SAML SSO 时。
对于具有现有 SAML 身份的用户，在访问组织的群组层次结构中的群组和项目时。用户可以使用其 SaaS 凭据查看其他群组和项目及其用户设置，而无需 SSO 登录。

如果满足以下一项或两项条件，则用户拥有 SAML 身份：

用户已使用极狐GitLab 群组的单点登录 URL 登录到极狐GitLab。
用户由 SCIM 提供。

每次访问时，系统不会提示用户通过 SSO 登录。极狐GitLab 检查用户是否已通过 SSO 进行身份验证。如果用户上次登录已超过 24 小时，极狐GitLab 会提示用户通过 SSO 再次登录。

SSO 的执行方式如下：

项目/群组可见性	强制 SSO 设置	有身份的成员	无身份的成员	无成员或未登录
私有	关闭	强制	非强制	非强制
私有	打开	强制	强制	强制
公开	关闭	强制	非强制	非强制
公开	打开	强制	强制	非强制

Web 活动强制执行仅 SSO 身份验证

当启用 对该群组的 Web 活动强制执行仅 SSO 身份验证 选项时：

所有成员都必须使用其极狐GitLab 群组的单点登录 URL 来访问极狐GitLab 群组资源，无论他们是否具有现有的 SAML 身份。
当用户访问组织的群组层次结构中的群组和项目时，会强制执行 SSO。用户无需 SSO 登录，可查看其他群组和项目。
无法手动将用户添加为新成员。
具有所有者角色的用户可以使用标准登录流程对顶级群组设置进行必要的更改。
对于非成员或未登录的用户：
- 当他们访问公开群组资源时，不会强制执行 SSO。
- 当他们访问私有群组资源时，会强制执行 SSO。

启用后，针对 Web 活动的 SSO 强制执行会产生以下影响：

对于群组，用户不能在顶级群组之外的群组中共享项目，即使该项目是派生的。
源自 CI/CD 作业的 Git 活动不强制执行 SSO 检查。
对于不与用户绑定的凭据（例如，项目和群组访问令牌以及部署密钥），不会强制执行 SSO 检查。
用户必须通过 SSO 登录才能使用依赖项代理拉取镜像。
启用 对该群组的 Git 和依赖代理活动强制执行仅 SSO 身份验证 选项时，涉及 Git 活动的任何 API 端点都将受到 SSO 强制执行。例如，创建或删除分支、提交或标签。对于通过 SSH 和 HTTPS 进行的 Git 活动，用户必须至少有一个通过 SSO 登录的活动会话，然后才能向极狐GitLab 仓库推送或拉取。

当对 Web 活动强制执行 SSO 时，非 SSO 群组成员不会立即失去访问权限。如果用户：

具有活动会话，他们可以继续访问群组长达 24 小时，直到身份提供商会话超时。
已注销，从身份提供商中删除后他们无法访问该群组。

故障排除

如果您发现很难明白极狐GitLab 和身份提供商之间的不同 SAML 术语：

查看您的身份提供商的文档，查看他们的 SAML 配置示例，了解有关他们使用的术语的信息。
查看用于私有化部署版实例的 SAML SSO 文档。私有化部署版实例的 SAML 配置文件支持比 SaaS 配置文件更多的选项。您可以在以下位置找到有关私有化部署版实例文件的信息：
- 外部 OmniAuth SAML 文档
- ruby-saml 库
将您的提供商提供的 XML 响应，与我们的用于内部测试的示例 XML 进行比较。