本文適用於:
- 組織安全管理員
SCIM 概覽
重要資訊: 若要為您的組織配置 SCIM 支援,您必須是一位組織安全性管理員。
什麼是 SCIM?
跨網域身分識別管理系統 (SCIM) 是一種開放性規格,專門用於讓管理使用者身分識別變得簡單和自動化。使用 SCIM,即可透過支援 SCIM 的身分識別提供者自動管理建立與中止 Workiva 使用者(例如 Okta、SailPoint IdentityIQ、PingFederate、OneLogin、Azure Active Directory 等)。
此外,SCIM 支援群組可用來管理組織角色、工作區成員、工作區角色與工作區群組。這可讓您透過偏好的身分識別提供者管理整個使用者生命週期。
SCIM 使用 2015 年發布的最新版本標準 SCIM 2.0。該服務可透過 HTTPS 存取,就像您目前使用的瀏覽器一樣,不需要新的防火牆規則或修改網路。
注意:Workiva 僅支援並協助疑難排解市售或可免費取得的 SCIM 用戶端配置。
支援的 SCIM 功能
支援以下佈建功能:
- 建立新的使用者
在身份提供者中指派的新使用者也會在 Workiva 平台中建立。 - 停用未指定用戶
在身份提供者中停用用戶將暫停該用戶在 Workiva 平台中的使用。 - 停用使用者
在身份提供者中停用使用者將暫停使用者在 Workiva 平台中的使用。 - 配置文件更新
通过身份提供者对使用者配置文件进行的更新将在 Workiva 平台中更新 - 匯入新的使用者
在 Workiva 平台建立新的使用者可匯入身份提供者,並對應到現有或新的使用者。 - 重新啟用使用者
在身份提供者中重新啟用使用者或重新指派使用者,將會在 Workiva 平台中啟用該使用者。 - 群組推送
使用者的 Workiva 權限,包括組織角色/職務(Organization Roles)、工作區成員(Workspace Memberships)、工作區角色/職務(Workspace Roles)和工作區群組成員(Workspace Group Memberships),可以由現有的身分提供者群組管理。
SCIM 與 SAML 單一登入
SCIM 應與 SAML 型單一登入 (SSO) 一起使用,後者透過身分識別提供者 (IdP) 提供對 Workiva 的存取權。在配置 SCIM 設定之前,請務必先檢閱 SAML 單一登入的基礎知識和配置 SAML 單一登入。
重要: 請確認所有 Workiva 的使用者名稱都有一致的命名慣例,並與 SCIM 工具將建立使用者的方式對齊/協調。
步驟 1:建立佈建
建立身分配置並產生 SCIM API 憑證:
- 按一下右上角的使用者圖示,然後從下拉式清單中選取 管理員 。
- 然後從下拉式清單中選取組織管理員。
- 在 組織管理員 頁面上,在左側功能表窗格中選取 安全性,然後選取 佈建索引標籤。
- 按一下AddIdentityorAPI。
-
在下拉式清單中選取「身分識別提供者」。
以下說明適用於身分識別提供者。關於 API 授與,請參閱 在組織管理員中建立和管理 API 授與。
- 輸入必填欄位:
- 為您的關聯設定完整名稱。該名稱應描述將傳送使用者資訊到 Workiva 的系統,例如「Okta 生產」。
-
設定 Workiva 使用者名稱。活動日誌中的 SCIM 動作歸屬於此使用者,並為它們產生 API 認證。
我們建議建立具有以下角色的專用 SCIM API 使用者:
- 組織使用者管理員(建立、停用和更新使用者所需)
- 組織安全性管理員(如果 SCIM 管理安全性管理員角色則需要)
- 組織工作區管理員(如果 SCIM 管理工作區成員資格、角色和群組,則需要)
- Workiva AI 使用者(如果 SCIM 管理 AI 角色則是必需的)
- 組織鏈結安全性管理員(如果 SCIM 管理鏈結角色則需要)
SCIM 只能指派和管理此使用者已有的角色。
此帳戶必須有有效的電子郵件地址才能產生 API 權杖。如果您稍後更改 Workiva 使用者名稱,目前的密碼將變為無效,且只有新使用者可以存取新密碼。
只有此使用者可以在 我的設定檔 > 安全性中檢視識別提供者密碼。
注意:如果 SCIM API 使用者沒有角色,則 SCIM 無法為其他使用者指派或管理該角色。例如,要透過 SCIM 佈建 Workiva AI 使用者或組織鏈安全性管理員角色,請先將這些角色指派給 SCIM API 使用者。
了解如何 更新組織角色 並檢視需要指派的角色。
- 設定認證類型。請參閱身分識別提供者的說明文件,以確定要使用的認證類型。
- OIN 中的 Workiva 應用程式僅支援基本驗證。
- Okta 建立的自訂應用程式可以支援 Bearer 權杖。
- 如果使用 Azure,請選取 Bearer 權杖。
- 或者為此身分提供者輸入說明。
- 在管理員聯絡人中輸入全名和電子郵件地址,這是貴方 IT 部門的技術聯絡人,發現問題或需要溝通未來的功能升級時,我們會與他聯絡。
- 按一下「建立佈建」(Create Provisioning) 以完成。
步驟 2:取得 ID 和 URL 值
您需要身分佈建 ID 和 URL 值以用於步驟 4:配置您的身分提供者。若要取得這些值:
- 在組織管理員中,前往安全性 > 佈建。
- 在身分提供者區段中找到您的佈建,然後複製 ID 和 URL 值。
步驟 3:取得基本驗證或 Bearer 權杖
若要取得新的基本驗證或 Bearer 權杖,您需要使用在步驟 1:建立佈建中指定的 SCIM 使用者的 Workiva 使用者名稱登入 Workiva 應用程式:
-
確保 SCIM 使用者帳戶擁有可供存取的有效電子郵件地址,且該 SCIM 使用者已新增至工作區。這是因為系統會傳送驗證電子郵件至 SCIM 使用者的電子郵件以進行登入。
附註: 如果SAML SSO 是必需的, 您需要新增此 SCIM 使用者為a SAML SSO 繞路使用者 以便使用使用者名稱和密碼登入。
- 前往 Workiva 登入畫面,並使用 SCIM 使用者的 Workiva 使用者名稱和密碼登入(如果您之前一直使用 SAML 單一登入,您需要先點擊變更使用者)。
- 在 Workiva 平台中,點擊右上角的設定檔圖示,前往我的設定檔 > 安全性。
- 在身分提供者區段中,點擊身分識別佈建旁的動作下拉式箭頭,然後點擊重新產生。
- 點擊重新產生以進行確認。
- 您將看到基本驗證密碼和 Bearer 權杖密碼。將密碼安全地記錄下來,因為您將無法再次看到這些密碼。
第 4 步:設定您的身份提供者
建立身分識別提供者後,您可以配置雲端型身分識別提供者軟體,或內部部署身分識別提供者軟體以連線至 Workiva。
- 確定您正在設定 SCIM 2.0 的連線,因為我們不支援舊版的 SCIM 協定。
- 如果您使用的是基本身份驗證類型,請注意您身份提供者軟體件中的「使用者名稱」應與「憑證」的「ID」與「密碼」相同。
請參閱下面的步驟,了解如何配置常見的身分識別提供者,或者如果您需要協助,請查閱您的提供者的說明文件和支援管道。
- 以管理員身分登入您的 Okta 組織。
- 開啟管理員入口網站。
- 開啟 Workiva 應用程式執行個體。
- 前往佈建選項卡。
- 在設定區段中,點擊配置 API 整合。
- 輸入您從步驟 2:取得 ID 和 URL 值中儲存的 URL 和 ID 值。
- 根據您在步驟 1:建立佈建中選擇的憑證類型,輸入您在步驟 3:取得基本驗證或 Bearer 權杖中獲得的基本驗證或 Bearer 權杖作為密碼。
- 點擊測試 API 憑證。如果測試成功,按一下儲存。
- 按一下「到應用程式」並向下捲動以選擇要啟用的配置功能。我們建議啟用建立使用者、更新使用者屬性和停用使用者。保留 Okta 預設使用者屬性對應不變。
- 按一下「儲存」(Save)。您現在可以透過分配選項卡,自動為 Workiva 組織層級的使用者進行設置和停用。
或者使用 Okta 的推送群組功能來管理使用者角色、工作區成員資格和工作區群組成員資格:
- 前往推送群組分頁並點擊設定圖示。
- 取消選取將應用程式群組重新命名以相符 Okta 中的群組名稱設定。按一下「儲存」(Save)。這樣可以減少連結時在 Workiva 中重新命名群組的可能性。
- 點擊重新整理應用程式群組以更新在 Workiva 中發生的任何匯入或變更,並確保 Workiva 中的所有群組都能呈現於 Okta。
- 點擊推送群組下拉式清單並選取按名稱查找群組。
-
若要將使用者角色、工作區成員資格和工作區群組從 Okta 同步到 Workiva,請將 Okta 群組連結到 Workiva 群組。可以針對希望 Okta 控制的每個使用者角色、工作區成員資格和工作區組成員資格完成此過程。
附註: Okta 必須依照步驟 5:管理使用者角色/職務 中所述的特定慣例,依據顯示名稱推送/拉動 SCIM 群組。
附註: 僅支援將 Okta 群組連結至 SCIM 群組。
- 按一下「儲存」(Save)。
- 如果連結成功,推送群組將作用中狀態顯示在推送群組清單中。 <!-- BEGIN: Okta Attributes & Expressions (Default Zendesk Template) -->
附註: Workiva 支援已匯入群組。
所需的 Okta 屬性和表達式
此表格列出 Okta 內每個預設屬性名稱及其對應的表達式。
| 屬性名稱 | Okta 表達式 |
|---|---|
使用者名稱 |
使用者名稱 |
givenName |
使用者名 |
家庭名 |
使用者姓氏 |
電子郵件 |
使用者的電子郵件 |
顯示名稱 |
使用者名稱 |
- 建立用於佈建的自訂應用程式,因為 Workiva 資源庫應用程式目前不支援 SCIM。點擊建立自己的應用程式並輸入 Workiva 作為名稱。選取整合您並未在資源庫上找到的任何其他應用程式(非資源庫)選項,然後點擊建立。
- 一旦建立自訂應用程式,以管理員身分登入您的 Azure 組織。
- 開啟管理員入口網站。
- 開啟 Workiva 應用程式執行個體。
- 前往佈建,然後按一下開始使用。
- 將佈建模式設為自動。
-
在 Azure 用戶端 URL 欄位中輸入您從步驟 2:取得 ID 和 URL 值儲存的 URL。
附註: Azure 在管理群組方面有一個已知問題。如要解決此問題,請在用戶端 URL 的末尾附加「?aadOptscim062020」。點擊此處以瞭解更多詳情。
- 在 Azure 密碼權杖欄位中輸入您在步驟 3:取得基本驗證或 Bearer 權杖取得的 Bearer 權杖。
- 按一下測試連線。如果測試成功,按一下儲存。
- 在對應區段中,按一下提供 Azure Active Directory 使用者。
- 在屬性對應頁面上,將已啟用設定為是。
- 在目標物件動作下,選取建立和更新。請勿選取刪除,因為 Workiva 不會刪除使用者設定檔,只會加以停用。
-
如下表所示來設定屬性對應:
customappsso 屬性 Microsoft Entra ID 屬性 使用者名稱 電子郵件|郵件 作用中 Switch([IsSoftDeleted], , “False”, “True”, “True”, “False”) 顯示名稱 顯示名稱 標題 jobTitle emails[type eq “work”].value 電子郵件|郵件 首選語言 首選語言 姓名.名字 givenName 姓名.姓氏 surname 外部 ID mailNickname
或者使用 Azure 的推送群組功能來管理使用者角色、工作區成員資格和工作區群組成員資格:
- 在佈建 > 對應區段中,按一下提供 Azure Active Directory 群組。
- 在屬性對應頁面上,將已啟用設定為是。
- 在來源物件範圍欄位中新增兩個篩選條件。此來源物件範圍允許 Azure 建立一個整體 Workiva 群組,該群組不會以群組的形式進行同步,以減少日誌中的錯誤。
- 第一個範圍篩選條件:
- 將來源屬性設定為說明。
- 將運算子設定為包括。
- 將子句值設定為工作區:
- 將範圍篩選條件標題輸入為工作區篩選條件。
- 第二個範圍篩選條件:
- 將來源屬性設定為說明。
- 將運算子設定為包括。
- 將子句值設定為角色:
- 將範圍篩選條件標題輸入為角色篩選條件。
- 第一個範圍篩選條件:
- 在目標物件動作下,選取更新。
-
如下表所示來設定屬性對應
customappsso 屬性 Microsoft Entra ID 屬性 顯示名稱 description* 外部 ID objectId 成員 成員 *此來源屬性可能會因環境和政策而變化。
-
若要將使用者角色、工作區成員資格和工作區群組從 Azure 同步到 Workiva,Azure 必須按照顯示名稱、自訂表達式或描述(如果政策允許)推送/提取 SCIM 群組,遵循步驟 5:管理使用者角色和群組描述的特定慣例。可以針對希望 Azure 控制的每個使用者角色、工作區成員資格和工作區組成員資格完成此過程。
附註: 如果政策允許 Azure 修改 Azure 安全控制項/控制措施群組的 description 屬性,則可以依據 SCIM 群組的說明推送/拉取 SCIM 群組。Azure 可因此在目錄中保留現有的 Azure 群組命名慣例。為此,請設定屬性對應為: customappsso AttributedisplayName to Microsoft Entra ID Attributedescription 。
- 返回佈建,並在設定區段中,將範圍設為僅同步分配的使用者和群組。
- 將佈建狀態設定為開啟。
-
返回 Workiva 應用程式實例下的主要佈建頁面,然後點擊隨需佈建以測試使用者是否正確地在 Workiva 中佈建。
附註: 如果您嘗試推送 Workiva All Users 群組,可能會發生錯誤,因為 Azure 會嘗試將群組作為群組推送,而非作為使用者推送。
- 測試成功後,點擊開始佈建,這將啟動 Azure 的初始佈建循環。調配時間間隔設定為 40 分鐘,可能需要一段時間,具體取決於人口數量和推送組。
步驟 5:管理使用者角色和群組
您可以透過 SCIM 群組指派組織角色、工作區成員資格、工作區角色和工作區群組。要使用 SCIM 群組來管理成員資格和角色,您的身分識別提供者必須按照下面說明的確切規定,按顯示名稱(或說明,如使用 Azure 且政策允許)推送/提取 SCIM 群組。
| 權利 | 顯示名稱格式 | 詳細資料 |
|---|---|---|
| 組織角色 | role:<role name> |
指派至具此名稱群組的人員,將獲派指定的組織角色。 例如:新增使用者至 SCIM 群組「角色:組織安全管理員」,則會授予使用者「組織安全管理員」組織角色。 |
| 工作區成員 | workspace:<workspace name> |
指派至具此名稱群組的人員將被新增為指定工作區的成員,並將觸發傳送歡迎加入工作區通知電子郵件。 例如:將使用者新增到 SCIM 群組「工作區:ABC Corp Internal 稽核」,將授予使用者「ABC Corp Internal 稽核」工作區的存取權,以及預設的「工作區成員」角色。 |
| 工作區角色 | workspace:<workspace name>:role:<workspace role name> |
指派至具有此名稱之群組的人員,將在指定的工作區中獲得指定的工作區角色。他們必須已經是工作區中的成員。如果他們還不是工作區中的成員,則在我們等待身分識別提供者請求將使用者新增至工作區時,我們的系統將保留最多 30 秒,然後就會失敗。如果在時間用完之前新增這些人員,此動作將繼續並成功完成。 例如:將使用者新增至 SCIM 群組「工作區:ABC Corp Internal 稽核:角色:管理員」會授予使用者「ABC Corp Internal 稽核」工作區中的「管理員」角色。 |
| 工作區群組 | 工作區:<workspace name>:群組:<workspace group name> |
指派至具有此名稱之群組的人員,將新增至指定工作區中的指定工作區群組。他們必須已經是工作區中的成員。如果他們還不是工作區中的成員,則在我們等待身分識別提供者請求將使用者新增至工作區時,我們的系統將保留最多 30 秒,然後就會失敗。如果在時間用完之前新增這些人員,此動作將繼續並成功完成。 例如:將使用者新增至 SCIM 群組「工作區:ABC Corp Internal 稽核:群組:編輯」會將該使用者新增至「ABC Corp Internal 稽核」工作區中的「編輯」工作區群組。 |
限制與最佳做法
在您使用使用者、角色與群組 SCIM 時,請將以下幾點銘記在心:
- 將由 SCIM 服務代表該使用者執行,因此我們強烈建議您為此建立一個專用的 API 使用者帳戶。活動日誌中的 SCIM 操作歸屬於您選擇的使用者,且該使用者必須具有組織使用者管理員、Org Workspace Admin、和組織安全性管理員角色。
- 不支援密碼同步。
- 從另一個組織邀請進入組織的使用者(例如稽核員或外部顧問)無法由 SCIM 管理。如果您的組織希望完全控制工作組織 中的第三方使用者,則需要為他們建立身分提供者帳戶,而不是從另一個組織新增使用者。
- 所有使用者必須填寫名字、姓氏、顯示名稱和電子郵件地址欄位。
- 名稱欄位中不允許使用變音符號。如果 使用者名稱中有這些字元,我們建議修改對應以替換它們。
- 使用 SCIM 群組新增使用者至工作區角色或工作區群組時,新增使用者必須已是工作區的成員(詳細資訊請參閱步驟 5:管理使用者角色和群組)。如果他們還不是工作區的成員,我們的系統將在等待您的身分提供者請求將使用者新增到工作區時保持最多 30 秒才會失敗。如果它們在時間耗盡之前遭新增,此操作將恢復並成功完成。
- 在執行批次指派使用者(20 人以上)至工作區角色或工作區群組時,最佳做法是確保先給予使用者工作區成員資格,再透過您的身份提供者執行呼叫,指派工作區角色或工作區群組。此操作順序可確保在嘗試進一步變更前(如新增工作區角色),正確新增使用者至工作區。
錯誤訊息
| 舊訊息 | 新訊息 | 錯誤原因 | 解決方案 |
| 找不到「{ATTRIBUTE NAME}」 | 無效的「{ATTRIBUTE NAME}」 | 「{ATTRIBUTE NAME}」提供的值無效 | 檢查「{ATTRIBUTE NAME}」的值是否正確 |
| 「{ATTRIBUTE NAME}」不存在 | 無效的「{ATTRIBUTE NAME}」 | 「{ATTRIBUTE NAME}」提供的值無效 | 檢查「{ATTRIBUTE NAME}」的值是否正確 |
| 「{ATTRIBUTE NAME}」已存在 | 「{ATTRIBUTE NAME}」已存在 | 「{ATTRIBUTE NAME}」提供的值已存在 | 輸入「{ATTRIBUTE NAME}」的唯一值 |
| 「{ATTRIBUTE NAME}」包含無效的空格字元 | 「{ATTRIBUTE NAME}」包含無效的空格字元 | 「{ATTRIBUTE NAME}」的提供值不能包含空格字元 | 移除空格字元 |
| 「{ATTRIBUTE NAME}」包含無效字元 | 「{ATTRIBUTE NAME}」包含無效字元 | 「{ATTRIBUTE NAME}」提供的值無效 | 輸入「{ATTRIBUTE NAME}」的有效值 |
| 「{ATTRIBUTE NAME}」包含禁用的「=」 | 「{ATTRIBUTE NAME}」包含無效字元「=」 | 「{ATTRIBUTE NAME}」提供的值包含無效字元 | 輸入「{ATTRIBUTE NAME}」的有效值 |
| 「{ATTRIBUTE NAME}」太長 | 「{ATTRIBUTE NAME}」不能超過 255 個字元 | 「{ATTRIBUTE NAME}」提供的值太長 | 輸入 255 個字元或更少的值 |
| 端點不存在 | 無效的端點 | 所提供的端點無效 | 檢查結構描述定義 |
| 不允許的方法 | 不支援的 HTTP 方法 | 您嘗試使用的 HTTP 方法不受端點支援 | 檢查目標端點支援哪些 HTTP 方法 |
| 無法修改角色名稱 | 無法修改角色名稱 | 您曾嘗試修改角色名稱 | 角色名稱無法修改 |
| 您提供了無效的工作區識別元,導致群組名稱格式有誤 | 無效的「workspaceName」 | 提供的工作區名稱無效 | 檢查工作區名稱是否正確 |
| 必須使用格式正確的電子郵件地址 | 電子郵件地址無效 | 提供的電子郵件地址無效 | 輸入有效的電子郵件地址 |
| 不允许使用電子郵件網域 | 電子郵件網域已被限制 | 提供的電子郵件網域已被限制 | 使用不同的電子郵件網域,或前往安全性 > 存取限制 > 電子郵件網域下從網域限制中移除該電子郵件網域。 |
| 無效時區 | 無效時區 | 所提供的時區無效 | 輸入有效的時區 |
| 無效的區域語言 | 無效的區域語言 | 所提供的區域語言無效 | 輸入有效的區域語言。有效的區域為「de_DE」、「en_US」、「es_AR」、「es_ES「、「es_MX」、「fr_FR」、「fr_CA」、「it_IT」、「nl_NL」、「pl_PL」、「zh_CN」、「zh_TW」、「ja_JP」、「ko_KR」及「pt_BR」。 |
| 公司電話太長 | 無效的電話號碼 | 所提供的電話號碼無效 | 輸入有效的電話號碼,或聯絡技術支援人員 |
| 以下位置的比較值無效…… | 無效的「篩選條件」表達式 | 提供的篩選條件表達式無效 | 請參考 https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.2 |
| 對於從 0 開始的標記,位置 18 處有未預期的字元「@」 | 無效的「篩選條件」表達式 | 提供的篩選條件表達式無效 | 請參考 https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.2 |
| 篩選條件字串意外中止 | 無效的「篩選條件」表達式 | 提供的篩選條件表達式無效 | 請參考 https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.2 |
| 未知的篩選條件屬性 | 無效的「篩選條件」表達式 | 提供的篩選條件表達式無效 | 請參考 https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.2 |
| 並未在結構描述中定義核心屬性「{ATTRIBUTE NAME}」 | 未定義「{ATTRIBUTE NAME}」屬性。檢查結構描述定義。 | 該屬性並未在結構描述中定義 | 檢查結構描述定義 |
| 「{ATTRIBUTE NAME}」屬性不具有多重值或複合值 | 「{ATTRIBUTE NAME}」屬性不能接受多重值或複合值 | 該屬性不能接受多重值或複合值 | 請檢查結構描述定義以了解該屬性的預期值 |
| 目標不可為空:「{ATTRIBUTE NAME}」 | 「{ATTRIBUTE NAME}」的值為必填 | 並未提供必填欄位的值 | 檢查結構描述定義中的必填欄位 |
| 未提供「{ATTRIBUTE NAME}」 | 「{ATTRIBUTE NAME}」的值為必填 | 並未提供必填欄位的值 | 檢查結構描述定義中的必填欄位 |
| 不可空白 | 「{ATTRIBUTE NAME}」的值為必填 | 並未提供必填欄位的值 | 檢查結構描述定義中的必填欄位 |
| 該主體不屬於工作區成員資格 | 該使用者不是工作區的成員 | 您曾嘗試將使用者新增至屬於不同工作區的群組 | 請先將使用者新增至工作區。然後將使用者新增至群組。 |
| 禁止 | 您沒有存取權。聯絡技術支援。 | 您沒有存取權 | 請聯絡技術支援以取得存取權 |
| 內部伺服器錯誤 | 發生錯誤。聯絡技術支援。 | 我們的系統出現了問題 | 請聯絡技術支援 |
需要協助嗎?
如果您在設定身分識別提供者時遇到任何問題或需要協助,您可以聯絡支援人員以獲得協助。