基于群组实现从 Azure AD 到极狐GitLab 的单点登录

本文来自
刘康 极狐(GitLab) 高级网站可靠性工程师

许多组织都有一套统一身份认证平台，通常基于组织架构或团队分工，以群组的方式将用户组织起来，比如 LDAP、Azure Active Directory（Azure AD）、Google Workspace、OneLogin、Authing 等，这种认证服务也被称为 Identity Provider（以下简称 IdP）。

基于 IdP，组织成员可以通过单点登录的方式，基于所分配的权限访问组织内的各个服务或系统，比如邮箱、OA、员工自助系统等。

极狐GitLab 同样支持接入各个组织自己的 IdP。

在极狐GitLab 中，企业或团队等组织通常是基于群组进行管理的。通过在 IdP 与极狐GitLab 群组建立关联，即可实现从 IdP 到极狐GitLab 的单点登录。其中，SAML 是一种广泛支持的，用于建立单点登录的协议。

本文将详细介绍如何基于“群组 SAML SSO” 配置从 Azure AD 到极狐GitLab 的单点登录。当然，对于其它的 IdP，也是类似的过程。

注：极狐GitLab 专业版和旗舰版支持该功能。

配置单点登录

作为 IdP，Azure AD 向其他系统的单点登录，通过企业应用程序（Enterprise Application）进行管理。

在 Azure AD 中创建企业应用

以具有 Azure AD 权限的账号登录 Azure，创建企业应用程序。

1. 进入 “Azure Active Directory”；
2. 左侧导航栏点击 “Enterprise applications”（企业应用程序）；
3. 点击 “+ New application”（+ 新建应用程序）按钮；
4. 点击 “+ Create your own application”（+ 创建你自己的应用程序），选择 “Integrate any other application you don't find in the gallery (Non-gallery)”（集成未在库中找到的任何其他应用程序(非库)）；
5. 为应用起一个容易识别的名字，比如 “jihulab.com” 或 “jihulab.com/mygroup1”，点击 “Create”（创建）按钮进行创建。

然后进入该企业应用程序，点击 “Single sign-on”（单一登录），选择 “SAML”。

SAML基础配置

在极狐GitLab，进入需要配置 SAML 的群组，点击 “Setting”（设置） → “SAML SSO”（SAML SSO(单点登录)）。

注：

1. 本文的例子是为 azure-saml-test 群组配置单点登录。
   引用
2. 本文截图是在 staging 环境截取的，因此其中的链接是 staging.jihulab.com。

请按下图示意互相填写信息（左侧为 Azure 单点登录配置页面，右侧为极狐GitLab SAML SSO 配置页面）：

注：在极狐GitLab SAML SSO 配置页面，“配置”（Configuration）部分，如果勾选“对该群组的 Web 活动强制执行仅 SSO 身份验证”（Enforce SSO-only authentication for web activity for this group），则该群组内将仅支持单点登录的身份，而无法通过常规的登录方式登录进来。

配置 Azure “Attributes & Claims”

两个系统在进行认证授权时，需要确定好用户属性的映射关系。比如 SAML 认证需要一个具有唯一性的字段来进行用户的关联，我们通常将 Azure 用户的 objectid 作为这个字段进行映射（user.userprincipalname 具有唯一性，也可以采用）。

在 Azure 的 “Attributes & Claims”（属性与声明）部分，点击 “Edit”（编辑）对默认的映射关系进行调整：

其中，

1. 对于 “Unique User Identifier”（唯一用户标识符），“Name identifier format”（名称标识符格式）选择 “Persistent”（永久），“Source attribute”（源属性）选择 user.objectid；
2. 其它只是涉及 claim 名称的调整。

至此，有关单点登录的部分就初步配置完成了。

配置用户同步

用户同步（User provision）是 SCIM 功能之一，可以将所在企业应用程序下的用户，自动创建到极狐GitLab，并且当用户发生增、改、删等变化时，会自动同步到极狐GitLab。

在极狐GitLab 创建 SCIM Token

该 Token 被 Azure 用来在极狐GitLab 对用户进行创建、更新等操作。

在极狐GitLab SAML SSO 设置页面靠下的位置，点击 “Generate a SCIM token”（生成 SCIM 令牌）按钮。

生成的令牌如下：

配置 Azure Provisioning

在 “Enterprise application”（企业应用程序）左侧导航栏中点击 “Provisioning”（预配），初次配置需要点击 “Get started”（开始）。

“Provisioning Mode”（预配模式）选择 “Automatic”（自动），然后填入刚刚生成的 URL 和 Token。测试成功后点击 “Save”（保存）。

此时下方会出现 “Mapping”（映射）菜单，展开并将 “Provision Azure Active Directory Groups” 设置为 Enabled=No（已启用=否），目前极狐GitLab 不支持。

这里是子群组层次结构的自动创建和同步，极狐GitLab 不支持。但是用户所属群组的信息可以同步，比如用户从群组 A 调整到 B，这种情况是可以同步的。
引用

接着，配置用户创建和同步时的属性映射关系。点击 “Provision Azure Active Directory Users” 进入，做如下映射关系的调整：

这里定义了当 Azure 推送用户属性到极狐GitLab，并在极狐GitLab 创建用户时，Azure AD 用户的哪些字段对应到极狐GitLab 用户的哪些字段。

1. 请确定配置有映射关系的用户属性是有值的，否则会导致创建用户失败，尤其是极狐GitLab 需要的字段，包括：

• externalId，前文配置单点登录时的 “Unique User Identifier”（唯一用户标识符）；
• userName，对应极狐GitLab 的用户账号，不可为空；
• emails[type eq "work"].value，极狐GitLab 将其用作用户邮箱，不可为空。注意，user.mail 有时是空的，如果 Azure 用户的邮箱是维护在其他字段（如 userPrincipalName），此处可以把 mail 替换为相应字段。

2. 映射关系的调整要和 SAML SSO 的 Attribute Mapping 一致。比如 externalId，如果前面配置的是 user.objectid，这里也要保持一致。这个字段的特殊之处在于，它是用来进行匹配的、具有唯一性的用户标识符，因此 ”Match objects using this attribute“（使用此属性匹配对象）是开启的，并且匹配优先级是最高的。如下图：

对于“必需”字段，可以在 “advanced options”（显示高级选项）下的 “Edit customappsso attributes list”（编辑 customappsso 的属性列表）中配置，将其 “Required?” 勾上。

Azure 手动用户预配

此时，我们就可以手动推送一个 Azure 用户到极狐GitLab 并尝试进行单点登录，以确认单点登录和用户预配的配置是否正确。

只有将 Azure AD 所管理的用户或组加入到配置 SAML SSO 的企业应用程序后，才可以进行单点登录。

在 Azure 的企业应用程序的左侧导航栏中点击 “Users and groups”（用户和组），然后点击 “+ Add user/group”（+ 添加用户/组），根据需要选择组或用户。

所选择的用户和组所包含的用户就可以进行用户预配和单点登录了。

点击 “Provisioning”（预配）下的 “Provision on demand”（按需预配），选择需要推送的用户，点击 “Provision”（配置）按钮；然后确认用户创建（或更新）的结果是否正确，各个字段的值是否正确：

这时在极狐GitLab 的 SAML SSO 配置页面应该就可以看到用户已经被创建，并且分配到群组下。

在群组的成员列表中也可以看到该用户，并且通过 SAML 标签标识了该用户是通过 SAML 方式创建的。

这时，被推送的用户的邮箱会收到欢迎邮件和确认邮件，请点击确认邮件中的链接完成邮箱的验证。

测试单点登录

然后，我们可以测试一下刚刚手动推送过来的用户，是否可以正常实现单点登录。

单点登录有多种方法，比如：

1. 通过 SAML SSO 配置页面中的 “GitLab single sign-on URL”（GitLab单点登录网址）登录，通常是类似
   https://jihulab.com/groups//-/saml/sso?token=xxxxxxxx这样的地址；
2. 如果在SAML SSO 配置页面，“配置”（Configuration）部分，勾选“对该群组的 Web 活动强制执行仅 SSO 身份验证”（Enforce SSO-only authentication for web activity for this group），则访问该群组地址的时候（https://jihulab.com/）就会自动跳转到 Azure 的登录页面。

正常情况下，在 Azure 登录页面中完成登录，或在 Azure 已经登录的状态下，会跳转到极狐GitLab 相关页面。第一次登录，需要完成邮箱和手机号验证，然后就可以进入群组页面：

Azure 自动用户同步

经过测试，单点登录和用户同步都配置正确，就可以开启 Azure 的自动用户同步了。

在 Azure “Provisioning”（预配）界面中，点击 “Started provisioning”（开始预配），开启自动的用户同步，被添加到当前企业应用程序中的用户和组（组中的用户）都会被自动同步到极狐GitLab 中，并且随着 Azure 中用户信息的调整自动更新。

如图，在日志中可以查看用户的创建或更新情况。

请注意，对于所选择的组下的子组中的用户，并不会被创建。 比如有这样的用户和组结构 group_a/group_aa/user_aa0，如果在企业应用程序中选择了 group_a 但没有选择 group_aa，则用户 user_aa0 并不会被创建和同步。

配置群组同步

有些用户希望能够将 Azure 侧的组和用户的组织架构，完整同步到极狐GitLab，这一功能可以部分实现：

• Azure 中的组并不会被自动同步到极狐GitLab 中，需要预先在极狐GitLab 中创建；
• Azure 和极狐GitLab 的组的对应关系需要手动维护；
• 用户对组的隶属关系可以自动更新到极狐GitLab。

假设 Azure AD 中的组织架构是这样的：

Azure AD
├── group_a
│   ├── group_aa
│   │   └── user_aa0
│   ├── user_a0
│   └── user_a1
└── group_b    
     └── user_b0

极狐GitLab 也有对应的子组关系：

则需要依次配置所有组的关联关系。

配置 SAML 群组链接

首先在 Azure AD “Groups”（组）下找到各个组的 “Object Id”（对象 ID）：

然后依次进入极狐GitLab 对应的子组下的 “Settings → SAML Group Links”（设置 → SAML 群组链接），配置关联关系和访问级别：

Azure 配置 Group Claim

两个系统的 groups 关联关系建立了，则用户进行 SSO 登录时，如果携带 group ID 信息，就会被极狐GitLab 按照预设的访问级别分配到对应的子组中。

因此需要配置 SAML SSO 的 “Attribute & Claims” 信息：

请注意，这里是选择 “+ Add a group claim”（+ 添加组声明）按钮，claim name 需要自定义为 Groups。

这样，当用户通过 Azure SAML SSO 登录到极狐GitLab 时，就可以拥有正确的子组权限了。如果 Azure AD 中该用户被迁移到另一个组中，当该用户再次登录时，极狐GitLab 会根据 SAML 响应中携带的 Groups 信息，为该用户赋予正确的子组权限，当然，前提是相关的子组与 Azure 的对应的组建立好链接。

可能遇到的问题

单点登录后又跳转到极狐GitLab 登录页，提示需要关联

如下图所示：

用户通过 SSO 到达 Jihulab.com 后，又跳转到登录页，上方提示如下：

• English: Sign in to GitLab to connect your organization's account
• 中文：登录 GitLab 以连接您组织的账户

原因在于，根据 SAML 登录所给出的用户信息（上面的用户属性映射信息，尤其是 Unique User Identifier），并未在 Jihulab.com 找到对应的用户，因此提示用户登录一下极狐GitLab（通常用于客户已经有 SaaS 账号，否则不建议客户这样操作），系统会将 SAML 账号与此时登录的账号进行关联，这个 SAML 用户以后再通过 SSO 就可以正常登录到极狐GitLab 了。

可能的原因：

• Azure 单点登录中配置的 “Unique User Identifier”（唯一用户标识）和 Azure Provisioning（预配）的映射关系不一致。
• 比如一个用的是 user.objectid，而另一个用的是 user.userPrincipalName；
• Azure 用户的对应邮箱已经在极狐GitLab 中存在，从而 Provisioning 没有成功，但极狐GitLab 发现该邮箱已存在，因此提示可能已经有账号请用户进行关联。

建议处理方式：

• 对于已经有 SaaS 账号的情况，比如有从 Gitlab.com 迁移到极狐GitLab 的客户，之前在 Gitlab.com 已经建立了 Azure AD 的 SSO 登录，也已经有了用户，需要请用户进行一次关联登录操作，操作时确保 Azure AD 和 SaaS 的账号是对应的。
• 对于确实没有 SaaS 账号的情况，需要先在 Azure 操作 User Provisioning，将用户创建过来。

有时候极狐GitLab 这边的群组是客户方 IT 工程师通过在极狐GitLab 注册的用户创建的，那么可以引导该工程师进行账号的关联操作，客户方其他用户还是通过用户推送的方式创建。

登录不成功，跳转到登录页，未提示要关联

请联系技术支持，请技术人员确认原因。

用户也可以借助 SAML 浏览器插件（如 SAML，WS-Federation and OAuth tracer）分析 SAML Response 中的 “Claims” 部分是否缺失部分信息（如 email），并查看 Azure 中的 Attribute & Claims 映射是否正确。

用户登录后立即从群组中消失

典型表现：

• 该用户登录后不是直接重定向到配置的群组下，而是出现类似新用户注册后第一次登录的页面，比如提问是什么角色，想要用极狐GitLab 做什么之类；
• 群组管理员查看发现该用户不在成员列表中了，查看 “Security & Compliance → Audit events”（安全 → 审计事件）发现该用户被从群组移除了，移除时间就发生在登录后的一两秒内；
• 请极狐GitLab 技术支持查看发现该用户还在，只是不在应该在的那个群组下了。

可能的原因是配置了 Azure SAML 单点登录的 group claim，但是没有正确配置极狐GitLab 的 “SAML 群组链接”。

参考

1. SAML SSO 单点登录

2. Azure AD SAML 单点登录配置示例

3. SAML Group Sync