SCIM provisioning using SAML SSO for GitLab.com groups · Gitlab 中文文檔

# SCIM provisioning using SAML SSO for GitLab.com groups > 原文：[https://docs.gitlab.com/ee/user/group/saml_sso/scim_setup.html](https://docs.gitlab.com/ee/user/group/saml_sso/scim_setup.html) * [Features](#features) * [Requirements](#requirements) * [GitLab configuration](#gitlab-configuration) * [Identity Provider configuration](#identity-provider-configuration) * [Azure configuration steps](#azure-configuration-steps) * [Configure attribute mapping](#configure-attribute-mapping) * [Okta configuration steps](#okta-configuration-steps) * [Okta Known Issues](#okta-known-issues) * [User access and linking setup](#user-access-and-linking-setup) * [Blocking access](#blocking-access) * [Troubleshooting](#troubleshooting) * [Azure](#azure) * [How do I verify my SCIM configuration is correct?](#how-do-i-verify-my-scim-configuration-is-correct) * [Testing Azure connection: invalid credentials](#testing-azure-connection-invalid-credentials) * [Azure: (Field) can’t be blank sync error](#azure-field-cant-be-blank-sync-error) * [How do I diagnose why a user is unable to sign in](#how-do-i-diagnose-why-a-user-is-unable-to-sign-in) * [How do I verify user’s SAML NameId matches the SCIM externalId](#how-do-i-verify-users-saml-nameid-matches-the-scim-externalid) * [Update or fix mismatched SCIM externalId and SAML NameId](#update-or-fix-mismatched-scim-externalid-and-saml-nameid) * [I need to change my SCIM app](#i-need-to-change-my-scim-app) # SCIM provisioning using SAML SSO for GitLab.com groups[](#scim-provisioning-using-saml-sso-for-gitlabcom-groups-silver-only "Permalink") [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9388) in [GitLab.com Silver](https://about.gitlab.com/pricing/) 11.10. 跨域身份管理系統（SCIM）是一種開放標準，可實現用戶自動配置. 當為 GitLab 組配置 SCIM 時，該組的成員資格將在 GitLab 和身份提供者之間同步. GitLab 的[SCIM API](../../../api/scim.html)實現[了 RFC7644 協議的](https://tools.ietf.org/html/rfc7644)一部分. ## Features[](#features "Permalink") 當前，可以執行以下操作： * 建立使用者 * 更新用戶（僅限 Azure） * 停用用戶支持以下身份提供者： * Azure * Okta ## Requirements[](#requirements "Permalink") * 必須配置[組單一登錄](index.html) . ## GitLab configuration[](#gitlab-configuration "Permalink") 配置[組單一登錄后](index.html) ，我們可以： 1. 導航到該組，然后單擊**管理> SAML SSO** . 2. 單擊**生成 SCIM 令牌**按鈕. 3. 保存令牌和 URL，以便可以在下一步中使用它們. [![SCIM token configuration](https://img.kancloud.cn/36/03/36031a093495f563be7358d4efd885bf_1202x805.png)](img/scim_token.png) ## Identity Provider configuration[](#identity-provider-configuration "Permalink") * [Azure](#azure-configuration-steps) * [Okta](#okta-configuration-steps) ### Azure configuration steps[](#azure-configuration-steps "Permalink") 現在需要為 SCIM 設置在[Azure 的](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/configure-single-sign-on-non-gallery-applications) [單點登錄](index.html)安裝過程中創建的 SAML 應用程序. 1. 檢查您的 GitLab SAML 應用程序的配置，并確保**名稱標識符值** （NameID）指向`user.objectid`或另一個唯一標識符. 這將與 GitLab 上使用的`extern_uid`匹配. [![Name identifier value mapping](https://img.kancloud.cn/16/c5/16c564c7f4ea6d0488c747bae3dc31f8_2428x810.png)](img/scim_name_identifier_mapping.png) 2. 通過遵循針對 Azure [支持](https://docs.microsoft.com/en-us/azure/active-directory/app-provisioning/use-scim-to-provision-users-and-groups#provisioning-users-and-groups-to-applications-that-support-scim)的 SCIM 安裝文檔[中支持 SCIM 的應用程序](https://docs.microsoft.com/en-us/azure/active-directory/app-provisioning/use-scim-to-provision-users-and-groups#provisioning-users-and-groups-to-applications-that-support-scim)的[供應用戶和組，來](https://docs.microsoft.com/en-us/azure/active-directory/app-provisioning/use-scim-to-provision-users-and-groups#provisioning-users-and-groups-to-applications-that-support-scim)設置自動供應和管理憑據. During this configuration, note the following: * `Tenant URL`和`secret token`是在[上一步中](#gitlab-configuration)檢索到的. * 如果 GitLab 的可用性有任何問題或類似錯誤，則通知電子郵件集將獲得這些信息. * 建議設置通知電子郵件并選中**發生故障時發送電子郵件通知**復選框. * 對于映射，我們將僅啟用"將`Synchronize Azure Active Directory Users to AppName`啟用狀態. 然后，您可以通過單擊" **測試連接"**來**測試連接** . 如果連接成功，請確保在繼續操作之前保存配置. 請參閱下面的[疑難解答](#troubleshooting) . #### Configure attribute mapping[](#configure-attribute-mapping "Permalink") 1. 單擊"將`Synchronize Azure Active Directory Users to AppName`以配置屬性映射. 2. 單擊`mail`映射旁邊的**刪除** . 3. 將`userPrincipalName`映射到`emails[type eq "work"].value`并將其**Matching 優先級**更改為`2` . 4. Map `mailNickname` to `userName`. 5. 確定 GitLab 如何唯一標識用戶. * 除非用戶已經為您的組鏈接了 SAML，否則請使用`objectId` . * 如果已經有鏈接 SAML 的用戶，則使用[SAML 配置中](#azure)的" `Name ID`值. 使用其他值可能會導致用戶重復并阻止用戶訪問 GitLab 組. 6. 創建一個新的映射： 1. 單擊**添加新映射** . 2. 組： * 上面確定的唯一標識符的**Source 屬性** ，通常是`objectId` . * **目標屬性**為`externalId` . * **使用此屬性**將**對象匹配**為`Yes` . * **匹配優先級**為`1` . 7. 單擊`userPrincipalName`映射，然后**使用此屬性**將**Match 對象**更改為`No` 8. 保存您的更改. 作為參考，您可以[在故障排除參考中](../../../administration/troubleshooting/group_saml_scim.html#azure-active-directory)查看[示例配置](../../../administration/troubleshooting/group_saml_scim.html#azure-active-directory) . **注意：**如果您使用**除** `objectId` **之外**的唯一標識符，請確保將其映射到`externalId` . 9. 在映射列表下，單擊**顯示高級選項>編輯 AppName 的屬性列表** . 10. 確保`id`是主要字段和必填字段，并且還需要`externalId` . **注意：** `username`既不是主要`username`也不是必需的，因為我們尚不支持 GitLab SCIM 上的該字段. 11. 保存所有屏幕，然后在**Provisioning**步驟中將`Provisioning Status`設置為`On` . [![Provisioning status toggle switch](https://img.kancloud.cn/af/47/af4754fa8daa3bbdaf9e8f03bdc6c360_723x210.png)](img/scim_provisioning_status.png) **注意：**您可以通過選擇`Scope`來控制實際同步的內容. 例如， `Sync only assigned users and groups`將僅同步分配給應用程序的`Users and groups` （ `Users and groups` ），否則，它將同步整個 Active Directory. 一旦啟用，同步細節的任何錯誤都出現在**供應**屏幕的底部，有一個鏈接到審計日志在一起. **警告：**同步后，將映射到`id`和`externalId`的字段更改可能會導致配置錯誤，用戶重復，并阻止現有用戶訪問 GitLab 組. ### Okta configuration steps[](#okta-configuration-steps "Permalink") 現在需要為 SCIM 設置在[Okta 的](https://developer.okta.com/docs/guides/build-sso-integration/saml2/overview/) [單點登錄](index.html#okta-setup-notes)安裝過程中創建的 SAML 應用程序. 在繼續之前，請確保完成[GitLab 配置](#gitlab-configuration)過程. 1. 登錄到 Okta. 2. 如果您在右上角看到一個**管理**按鈕，請單擊該按鈕. 這將確保您位于"管理"區域. **提示：**如果您在使用開發者控制臺，點擊**開發者控制臺**頂部欄并選擇**經典的 UI.** 否則，您可能看不到以下步驟中描述的按鈕： 3. 在" **應用程序"**選項卡中，單擊" **添加應用程序"** . 4. Search for **GitLab**, find and click on the ‘GitLab’ application. 5. 在 GitLab 應用程序概述頁面上，單擊**添加** . 6. 在" **應用程序可見性"下，**選中兩個復選框. 當前，GitLab 應用程序不支持 SAML 身份驗證，因此不應向用戶顯示該圖標. 7. 單擊**"完成"**以完成添加應用程序. 8. 在**供應**標簽中，點擊**配置 API 集成** . 9. Select **啟用 API 集成**. * 對于**基本 URL，**輸入從 GitLab SCIM 配置頁面獲得的 URL. * 對于**API 令牌，**輸入從 GitLab SCIM 配置頁面獲得的 SCIM 令牌. 10. 點擊"測試 API 憑據"以驗證配置. 11. 單擊**保存**以應用設置. 12. After saving the API integration details, new settings tabs will appear on the left. Choose **到應用**. 13. Click **Edit**. 14. 選中"為**創建用戶**和**停用用戶** **啟用** "復選框. 15. Click **Save**. 16. 在" **分配"**選項卡中分配用戶. 分配的用戶將在您的 GitLab 組中創建和管理. #### Okta Known Issues[](#okta-known-issues "Permalink") Okta GitLab 應用程序當前僅支持 SCIM. 繼續使用單獨的 Okta [SAML SSO](index.html)配置以及上述新的 SCIM 應用程序. ## User access and linking setup[](#user-access-and-linking-setup "Permalink") 只要已經配置了[Group SAML](index.html) ，就可以在啟用同步之前，在激活同步之前，現有的 GitLab.com 用戶可以通過以下方式之一鏈接到其帳戶： * 通過更新其 GitLab.com 用戶帳戶中的*主要*電子郵件地址以匹配其身份提供商的用戶個人資料電子郵件地址. * 通過執行以下步驟： 1. 如果需要，登錄到 GitLab.com. 2. 在身份提供商的儀表板上單擊 GitLab 應用程序，或訪問**GitLab 單一登錄 URL** . 3. 單擊**授權**按鈕. 后續訪問中的新用戶和現有用戶可以通過身份提供商的儀表板或直接訪問鏈接來訪問組. 有關角色信息，請參閱[組 SAML 頁面](index.html#user-access-and-management) ### Blocking access[](#blocking-access "Permalink") 要取消對該組的訪問，我們建議從身份提供商或特定應用程序的用戶列表中刪除該用戶. 在下一次同步時，將取消提供該用戶，這意味著該用戶將從組中刪除. 除非使用[組托管帳戶，](group_managed_accounts.html)否則不會刪除該用戶帳戶. ## Troubleshooting[](#troubleshooting "Permalink") 本節包含可能遇到的問題的可能解決方案. ### Azure[](#azure "Permalink") #### How do I verify my SCIM configuration is correct?[](#how-do-i-verify-my-scim-configuration-is-correct "Permalink") 查看以下內容： * 確保`id`的 SCIM 值與`NameId`的 SAML 值匹配. * 確保`externalId`的 SCIM 值與`NameId`的 SAML 值匹配. 查看以下 SCIM 參數以獲取合理的值： * `userName` * `displayName` * `emails[type eq "work"].value` #### Testing Azure connection: invalid credentials[](#testing-azure-connection-invalid-credentials "Permalink") 測試連接時，您可能會遇到錯誤： **您似乎輸入了無效的憑據.** **請確認您使用的管理帳戶信息正確** . 如果`Tenant URL`和`secret token`正確，請檢查您的組路徑中是否包含可能被視為無效 JSON 原語的字符（例如`.` ）. 從組路徑中刪除此類字符通常可以解決該錯誤. #### Azure: (Field) can’t be blank sync error[](#azure-field-cant-be-blank-sync-error "Permalink") 在檢查供應的審核日志時，有時您會看到錯誤`Namespace can't be blank, Name can't be blank, and User can't be blank.` 這可能是由于沒有為所有要映射的用戶提供所有必填字段（例如名字和姓氏）. 作為解決方法，請嘗試其他映射： 1. 請按照上面的 Azure 映射說明進行操作. 2. 刪除`name.formatted`目標屬性條目. 3. 將`displayName`源屬性更改為具有`name.formatted`目標屬性. #### How do I diagnose why a user is unable to sign in[](#how-do-i-diagnose-why-a-user-is-unable-to-sign-in "Permalink") 每當`id`或`externalId`更改時，SCIM 都會更新 GitLab 存儲的**Identity** （ `extern_uid` ）值. 除非 GitLab 標識（ `extern_uid` ）值與 SAML 發送的`NameId`匹配，否則用戶將無法登錄. SCIM 還將使用此值來匹配`id`上的用戶，并且只要`id`或`externalId`值發生更改，SCIM 就會更新此值. 將此 SCIM `id`和 SCIM `externalId`配置為與 SAML `NameId`相同的值很重要. 可以使用[調試工具](./index.html#saml-debugging-tools)跟蹤 SAML 響應，并且可以根據我們的[SAML 故障排除文檔](./index.html#troubleshooting)檢查任何錯誤. #### How do I verify user’s SAML NameId matches the SCIM externalId[](#how-do-i-verify-users-saml-nameid-matches-the-scim-externalid "Permalink") 組所有者可以在組 SAML SSO 設置頁面中查看用戶列表和為每個用戶存儲的`externalId` . 另外，在[SCIM API](../../../api/scim.html#get-a-list-of-saml-users)可用于手動檢索`externalId` ，我們已經存儲了用戶，也被稱為`external_uid`或`NameId` . 例如： ``` curl 'https://example.gitlab.com/api/scim/v2/groups/GROUP_NAME/Users?startIndex=1"' --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json" ``` 要查看它與作為 SAML NameId 返回的值的比較，可以讓用戶使用[SAML Tracer](index.html#saml-debugging-tools) . #### Update or fix mismatched SCIM externalId and SAML NameId[](#update-or-fix-mismatched-scim-externalid-and-saml-nameid "Permalink") 無論是更改值還是需要映射到其他字段，請確保`id` ， `externalId`和`NameId`都映射到同一字段. 如果 GitLab 的`externalId`與 SAML NameId 不匹配，則需要對其進行更新才能使用戶登錄.理想情況下，將身份標識提供者配置為進行此類更新，但是在某些情況下，它可能無法這樣做. ，例如在查找用戶時由于 ID 更改而失敗. 如果您修改 SCIM 身份提供程序使用的字段，請務必謹慎，通常為`id`和`externalId` . 我們使用這些 ID 查找用戶. 如果身份提供者不知道這些字段的當前值，則該提供者可以創建重復的用戶. 如果用戶的`externalId`不正確，并且也與 SAML NameID 不匹配，則可以通過以下方式解決該問題： * 您可以根據[" SAML 身份驗證失敗：用戶已被使用"](./index.html#message-saml-authentication-failed-user-has-already-been-taken)部分，使用戶取消鏈接并重新鏈接自己. * 通過在啟用預配置的同時從 SAML 應用中刪除所有用戶，可以同時取消所有用戶的鏈接. * 您可以使用[SCIM API](../../../api/scim.html#update-a-single-saml-user)手動更正為用戶存儲的`externalId`以匹配 SAML `NameId` . 要查找用戶，您需要知道與`NameId`以及當前`externalId`匹配的`NameId` . 然后可以發出手動 SCIM＃update 請求，例如： ``` curl --verbose --request PATCH 'https://gitlab.com/api/scim/v2/groups/YOUR_GROUP/Users/OLD_EXTERNAL_UID' --data '{ "Operations": [{"op":"Replace","path":"externalId","value":"NEW_EXTERNAL_UID"}] }' --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json" ``` 重要的是不要將這些值更新為不正確的值，因為這將導致用戶無法登錄.也不要將值分配給錯誤的用戶，這也很重要，因為這將導致用戶登錄到錯誤的帳戶. #### I need to change my SCIM app[](#i-need-to-change-my-scim-app "Permalink") 各個用戶可以按照[" SAML 身份驗證失敗：用戶已被使用"](./index.html#i-need-to-change-my-saml-app)部分中的說明進行操作. 或者，可以從 SCIM 應用程序中刪除用戶，這將取消所有已刪除用戶的鏈接. 然后可以為新的 SCIM 應用打開同步，以[鏈接現有用戶](#user-access-and-linking-setup) .