许多组织都有一套统一身份认证平台,通常基于组织架构或团队分工,以群组的方式将用户组织起来,比如 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,创建企业应用程序。
然后进入该企业应用程序,点击 “Single sign-on”(单一登录),选择 “SAML”。
在极狐 GitLab,进入需要配置 SAML 的群组,点击 “Setting”(设置) → “SAML SSO”(SAML SSO(单点登录))。
注:
- 本文的例子是为
azure-saml-test
群组配置单点登录。- 本文截图是在 staging 环境截取的,因此其中的链接是
staging.jihulab.com
。
请按下图示意互相填写信息(左侧为 Azure 单点登录配置页面,右侧为极狐 GitLab SAML SSO 配置页面):
注:在极狐 GitLab SAML SSO 配置页面,“配置”(Configuration)部分,如果勾选“对该群组的 Web 活动强制执行仅 SSO 身份验证”(Enforce SSO-only authentication for web activity for this group),则该群组内将仅支持单点登录的身份,而无法通过常规的登录方式登录进来。
两个系统在进行认证授权时,需要确定好用户属性的映射关系。比如 SAML 认证需要一个具有唯一性的字段来进行用户的关联,我们通常将 Azure 用户的 objectid
作为这个字段进行映射(user.userprincipalname
具有唯一性,也可以采用)。
在 Azure 的 “Attributes & Claims”(属性与声明)部分,点击 “Edit”(编辑)对默认的映射关系进行调整:
其中,
user.objectid
;
至此,有关单点登录的部分就初步配置完成了。
用户同步(User provision)是 SCIM 功能之一,可以将所在企业应用程序下的用户,自动创建到极狐 GitLab,并且当用户发生增、改、删等变化时,会自动同步到极狐 GitLab。
该 Token 被 Azure 用来在极狐 GitLab 对用户进行创建、更新等操作。
在极狐 GitLab SAML SSO 设置页面靠下的位置,点击 “Generate a SCIM token”(生成 SCIM 令牌)按钮。
生成的令牌如下:
在 “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 用户到极狐 GitLab 并尝试进行单点登录,以确认单点登录和用户预配的配置是否正确。
只有将 Azure AD 所管理的用户或组加入到配置 SAML SSO 的企业应用程序后,才可以进行单点登录。
在 Azure 的企业应用程序的左侧导航栏中点击 “Users and groups”(用户和组),然后点击 “+ Add user/group”(+ 添加用户/组),根据需要选择组或用户。
所选择的用户和组所包含的用户就可以进行用户预配和单点登录了。
点击 “Provisioning”(预配)下的 “Provision on demand”(按需预配),选择需要推送的用户,点击 “Provision”(配置)按钮;然后确认用户创建(或更新)的结果是否正确,各个字段的值是否正确:
这时在极狐 GitLab 的 SAML SSO 配置页面应该就可以看到用户已经被创建,并且分配到群组下。
在群组的成员列表中也可以看到该用户,并且通过 SAML 标签标识了该用户是通过 SAML 方式创建的。
这时,被推送的用户的邮箱会收到欢迎邮件和确认邮件,请点击确认邮件中的链接完成邮箱的验证。
然后,我们可以测试一下刚刚手动推送过来的用户,是否可以正常实现单点登录。
单点登录有多种方法,比如:
https://jihulab.com/groups//-/saml/sso?token=xxxxxxxx
这样的地址;https://jihulab.com/
)就会自动跳转到 Azure 的登录页面。
正常情况下,在 Azure 登录页面中完成登录,或在 Azure 已经登录的状态下,会跳转到极狐 GitLab 相关页面。第一次登录,需要完成邮箱和手机号验证,然后就可以进入群组页面:
经过测试,单点登录和用户同步都配置正确,就可以开启 Azure 的自动用户同步了。
在 Azure “Provisioning”(预配)界面中,点击 “Started provisioning”(开始预配),开启自动的用户同步,被添加到当前企业应用程序中的用户和组(组中的用户)都会被自动同步到极狐 GitLab 中,并且随着 Azure 中用户信息的调整自动更新。
如图,在日志中可以查看用户的创建或更新情况。
请注意,对于所选择的组下的子组中的用户,并不会被创建。 比如有这样的用户和组结构 group_a/group_aa/user_aa0
,如果在企业应用程序中选择了 group_a
但没有选择 group_aa
,则用户 user_aa0
并不会被创建和同步。
有些用户希望能够将 Azure 侧的组和用户的组织架构,完整同步到极狐 GitLab,这一功能可以部分实现:
假设 Azure AD 中的组织架构是这样的:
Azure AD
├── group_a
│ ├── group_aa
│ │ └── user_aa0
│ ├── user_a0
│ └── user_a1
└── group_b
└── user_b0
极狐 GitLab 也有对应的子组关系:
则需要依次配置所有组的关联关系。
首先在 Azure AD “Groups”(组)下找到各个组的 “Object Id”(对象 ID):
然后依次进入极狐 GitLab 对应的子组下的 “Settings → SAML Group Links”(设置 → SAML 群组链接),配置关联关系和访问级别:
两个系统的 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 的对应的组建立好链接。
如下图所示:
用户通过 SSO 到达 Jihulab.com 后,又跳转到登录页,上方提示如下:
原因在于,根据 SAML 登录所给出的用户信息(上面的用户属性映射信息,尤其是 Unique User Identifier),并未在 Jihulab.com 找到对应的用户,因此提示用户登录一下极狐 GitLab(通常用于客户已经有 SaaS 账号,否则不建议客户这样操作),系统会将 SAML 账号与此时登录的账号进行关联,这个 SAML 用户以后再通过 SSO 就可以正常登录到极狐 GitLab 了。
可能的原因:
user.objectid
,而另一个用的是 user.userPrincipalName
;
建议处理方式:
有时候极狐 GitLab 这边的群组是客户方 IT 工程师通过在极狐 GitLab 注册的用户创建的,那么可以引导该工程师进行账号的关联操作,客户方其他用户还是通过用户推送的方式创建。
请联系技术支持,请技术人员确认原因。
用户也可以借助 SAML 浏览器插件(如 SAML,WS-Federation and OAuth tracer)分析 SAML Response 中的 “Claims” 部分是否缺失部分信息(如 email),并查看 Azure 中的 Attribute & Claims 映射是否正确。
典型表现:
可能的原因是配置了 Azure SAML 单点登录的 group claim,但是没有正确配置极狐 GitLab 的 “SAML 群组链接”。
参考