本文來自
劉康 極狐(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，創建企業應用程序。
- 進入 “Azure Active Directory”；
- 左側導航欄點擊 “Enterprise applications”（企業應用程序）；
- 點擊 “+ New application”（+ 新建應用程序）按鈕；
- 點擊 “+ Create your own application”（+ 創建你自己的應用程序），選擇 “Integrate any other application you don't find in the gallery (Non-gallery)”（集成未在庫中找到的任何其他應用程序(非庫)）；
- 為應用起一個容易識別的名字，比如 “jihulab.com” 或 “jihulab.com/mygroup1”，點擊 “Create”（創建）按鈕進行創建。
然後進入該企業應用程序，點擊 “Single sign-on”（單一登錄），選擇 “SAML”。
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），則該羣組內將僅支持單點登錄的身份，而無法通過常規的登錄方式登錄進來。
配置 Azure “Attributes & Claims”
兩個系統在進行認證授權時，需要確定好用户屬性的映射關係。比如 SAML 認證需要一個具有唯一性的字段來進行用户的關聯，我們通常將 Azure 用户的 objectid 作為這個字段進行映射（user.userprincipalname 具有唯一性，也可以採用）。
在 Azure 的 “Attributes & Claims”（屬性與聲明）部分，點擊 “Edit”（編輯）對默認的映射關係進行調整：
其中，
- 對於 “Unique User Identifier”（唯一用户標識符），“Name identifier format”（名稱標識符格式）選擇 “Persistent”（永久），“Source attribute”（源屬性）選擇
user.objectid； - 其它只是涉及 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 替換為相應字段。
- 映射關係的調整要和 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 方式創建的。
這時，被推送的用户的郵箱會收到歡迎郵件和確認郵件，請點擊確認郵件中的鏈接完成郵箱的驗證。
測試單點登錄
然後，我們可以測試一下剛剛手動推送過來的用户，是否可以正常實現單點登錄。
單點登錄有多種方法，比如：
- 通過 SAML SSO 配置頁面中的 “GitLab single sign-on URL”（GitLab單點登錄網址）登錄，通常是類似
https://jihulab.com/groups//-/saml/sso?token=xxxxxxxx這樣的地址； - 如果在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
