乐趣区

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

jiezi

本文来自
刘康 极狐(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 替换为相应字段。
  1. 映射关系的调整要和 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

退出移动版