:
- 组织安全管理员
SCIM概述
重要提示:要为您的组织配置 SCIM支持,您必须是组织安全管理员
。
什么是SCIM?
跨域身份管理系统 (SCIM) 是一项开放规范,旨在简化和自动化用户身份管理。使用 SCIM,您可以通过支持 SCIM 的身份提供商(例如 Okta、SailPoint IdentityIQ、PingFederate、OneLogin、Azure Active Directory 等)自动管理 Workiva 用户的创建和暂停。
此外,SCIM 还支持群组,以便管理组织角色、工作区成员、工作区角色和工作区群组。这样,您就可以通过您首选的身份提供商管理整个用户生命周期。
SCIM 使用的是 2015 年发布的最新版本标准 SCIM 2.0。该服务通过 HTTPS 访问,就像您现在的浏览器一样,无需新的防火墙规则或网络修改。
注:Workiva 仅支持并协助排查商业或免费 SCIM 客户端的配置问题。
支持的SCIM功能
支持以下配置功能:
- 创建新用户
在身份提供商中分配的新用户也将在 Workiva 平台中创建。 - 停用未分配的用户
在身份提供商中取消分配用户将暂停该用户在 Workiva 平台中的访问权限 - 停用用户
在身份提供商中停用用户将暂停该用户在 Workiva 平台上的帐户 - 个人资料更新
通过身份提供商对用户个人资料所做的更新将在 Workiva 平台中更新。 - 导入新用户
在 Workiva 平台创建的新用户可以导入到身份提供商,并映射到现有用户或新用户。 - 重新激活用户
在身份提供商中重新激活或重新分配用户,即可在 Workiva 平台中激活该用户。 - 群组推送
用户的 Workiva 权限,包括组织角色、工作区成员资格、工作区角色和工作区组成员资格,可以通过现有的身份提供程序组进行管理。
SCIM 和 SAML 单点登录
SCIM 应与基于 SAML 的单点登录 (SSO) 结合使用,后者可通过您的身份提供商 (IdP) 提供对 Workiva 的访问。在配置 SCIM 设置之前,请确保您已查看 SAML 单点登录基础知识 和 配置 SAML 单点登录。
重要提示 :请确认所有 Workiva 用户名均采用一致的命名规则,并与 SCIM 工具创建用户的方式保持一致
。
步骤 1:创建配置
创建身份配置并生成 SCIM API 凭证:
- 在右上角,点击用户图标,然后从下拉菜单中选择 管理员 。
- 然后从下拉菜单中选择组织管理员。
- 在 “组织管理 ”页面上,选择左侧菜单窗格中的 “安全” ,然后选择 “配置”选项卡。
- 点击 添加身份或 API。
-
在下拉菜单中选择身份提供商 。
以下说明适用于身份提供商。有关 API 授权,请参阅 在组织管理中创建和管理 API 授权
。 - 请填写必填项:
- 为您的协会设置一个全名。该名称应描述将向 Workiva 发送用户信息的系统,例如“Okta Production”。
-
设置 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 Token。
- 如果使用 Azure,请选择 Bearer Token。
- (可选)输入此身份提供 程序的描述。
- 在 管理员联系人下,输入您 IT 部门内技术联系人的 全名 和 电子邮件地址 ,以便我们在出现问题或沟通未来功能增强时可以联系到他们。
- 点击 创建配置 完成。
步骤 2:获取 ID 和 URL 值
您需要身份配置 ID 和 URL 值,以便执行 第 4 步:配置您的身份提供商。要获得这些值:
- 在组织管理中,转到 安全 > 配置。
- 在 身份提供商 部分下,找到您的配置信息,并复制 ID 和 URL 值。
步骤 3:获取基本身份验证或持有者令牌
要获取新的基本身份验证或持有者令牌,您需要使用您在“步骤 1:创建配置”中指定的 SCIM用户 Workiva 用户名 登录 Workiva 应用程序:
-
确保 SCIM 用户帐户具有可访问的有效电子邮件地址,并且 SCIM 用户已添加到工作区。这是因为系统会向 SCIM 用户的邮箱发送验证邮件,以便用户登录。
注意:如果需要 SAML单点登录,则需要将此 SCIM 用户添加为 SAML SSO 绕过用户,以便使用用户名和密码登录。
- 前往 Workiva 登录屏幕,并使用 SCIM 用户的 Workiva 用户名和密码登录(如果您之前一直使用 SAML SSO 登录,则需要先点击 更改用户)。
- 在 Workiva 平台上,点击右上角的个人资料图标,然后转到 我的个人资料 > 安全。
- 在 身份提供程序 部分,单击身份配置旁边的 操作 下拉箭头,然后单击 重新生成。
- 点击 重新生成进行确认。
- 您会看到 基本身份验证密钥 和 持有者令牌密钥。把这些秘密抄写到安全的地方,因为你以后再也看不到这些秘密了。
步骤 4:配置您的身份提供商
创建身份提供商后,您可以配置基于云或本地的身份提供商软件以连接到 Workiva。
- 请确保您使用的是 SCIM 2.0 连接,因为我们不支持 SCIM 协议的早期版本。
- 如果您使用的是基本身份验证凭据类型,请注意,在您的身份提供商软件中,“用户名”与“ID”同义,“密码”与“凭据”同义。
有关如何配置常用身份提供商的步骤,请参阅以下步骤;如果您需要帮助,请查阅提供商的文档和支持渠道。
- 以管理员身份登录您的 Okta 组织。
- 打开管理员门户。
- 打开您的 Workiva 应用实例。
- 转到 配置 选项卡。
- 在 设置 部分,单击 配置 API 集成。
- 输入您从 步骤 2:获取 ID 和 URL 值中保存的 URL 和 ID 值。
- 根据您在 步骤 1:创建配置中选择的凭证类型,输入您在 步骤 3:获取基本身份验证或 Bearer 令牌中获得的基本身份验证或 Bearer 令牌作为 密码。
- 点击 测试 API 凭据。如果测试成功,请点击 保存。
- 点击 进入应用 ,向下滚动选择要启用的配置功能。我们建议启用 创建用户、 更新用户属性和 停用用户。保持 Okta 默认用户属性映射不变。
- 点击 保存。现在,您可以通过 Okta 在 Workiva 组织级别通过 分配 选项卡自动配置和停用用户。
(可选)使用 Okta 的推送组功能来管理用户角色、工作区成员资格和工作区组成员资格:
- 转到 推送群组 选项卡,然后单击设置图标。
- 取消选中 将应用程序组重命名为与 Okta 中的组名称匹配 设置。点击 保存。这样就避免了在 Workiva 中进行链接时重命名群组的可能性。
- 点击 刷新应用组 以更新 Workiva 中发生的任何导入或更改,并确保 Workiva 中的所有组都在 Okta 中得到体现。
- 点击 推送群组 下拉菜单,然后选择 按名称查找群组。
-
要将 Okta 中的用户角色、工作区成员和工作区组同步到 Workiva,请将 Okta 组链接到 Workiva 组。对于您希望 Okta 控制的每个用户角色、工作区成员身份和工作区组成员身份,都需要完成此操作。
注:Okta 必须按照步骤 5:管理用户角色和组中描述的特定约定,通过显示名称推送/拉取 SCIM 组。
注:仅支持将 Okta 群组链接到 SCIM 群组。
- 点击 保存。
- 如果链接成功,推送组将出现在推送组列表中,状态为 Active 。 <!-- BEGIN: Okta Attributes & Expressions (Default Zendesk Template) -->
注:Workiva 支持导入群组。
Okta 必需属性和表达式
此表列出了 Okta 中的每个默认属性名称及其对应的表达式。
| 属性名称 | Okta表达式 |
|---|---|
用户名 |
用户名 |
给定的名称 |
用户.名字 |
姓 |
用户姓氏 |
电子邮件 |
用户邮箱 |
显示名称 |
用户.显示名称 |
- 请创建一个自定义应用程序进行配置,因为 Workiva Gallery 应用程序目前不支持 SCIM。点击 创建您自己的应用程序 ,然后输入 Workiva 作为名称。选择 集成您在库中找不到的任何其他应用程序(非库) 选项,然后单击 创建。
- 自定义应用程序创建完成后,以管理员身份登录到您的 Azure 组织。
- 打开管理员门户。
- 打开您的 Workiva 应用实例。
- 转到 配置,然后单击 开始。
- 将 配置模式 设置为 自动。
-
在 Azure 租户 URL [ 字段中输入您从 步骤 2:获取 ID 和 URL 值保存的 URL。
注意:Azure 在管理组方面存在已知问题。要解决此问题,请在租户 URL 的末尾添加“?aadOptscim062020”。详情请见此处。
- 在 步骤 3:获取基本身份验证或 Bearer 令牌 中获取的 Bearer 令牌输入到 Azure 密钥令牌 字段中。
- 点击 测试连接。如果测试成功,请点击 保存。
- 在 映射 部分中,单击 预配 Azure Active Directory 用户。
- 在 属性映射 页面上,将 启用 设置为 是。
- 在 目标对象操作下,选择 创建 和 更新。请勿选择“删除”,因为 Workiva 不会删除用户个人资料,而只会停用它们。
-
请按下表所示设置 属性映射 :
自定义应用程序属性 Microsoft Entra ID 属性 用户名 邮件 活动 Switch([IsSoftDeleted], , “False”, “True”, “True”, “False”) 显示名称 显示名称 所有权 职称 emails[type eq “work”].value 邮件 首选语言 首选语言 名字.givenName 给定的名称 姓名.姓氏 姓 externalId 邮件昵称
(可选)使用 Azure 的推送组功能来管理用户角色、工作区成员身份和工作区组成员身份:
- 在 “预配 > 映射 ”部分中,单击 “预配 Azure Active Directory 组” 。
- 在 属性映射 页面上,将 启用 设置为 是。
- 向 源对象范围 字段添加两个范围过滤器。此 源对象范围 允许 Azure 创建一个不会作为组同步的总体 Workiva 组,以减少日志中的错误。
- 第一个范围过滤器:
- 设置 源属性 为 描述。
- 设置 运算符 为 INCLUDES。
- 将 子句值 设置为 工作区:
- 输入 范围筛选器标题 作为 工作区筛选器。
- 对于第二个范围过滤器:
- 设置 源属性 为 描述。
- 设置 运算符 为 INCLUDES。
- 设置 子句值 到 角色:
- 输入 范围筛选器标题 作为 角色筛选器。
- 第一个范围过滤器:
- 在 目标对象操作下,选择 更新。
-
请按照下表所示设置 属性映射
自定义应用程序属性 Microsoft Entra ID 属性 显示名称 描述* externalId objectId 成员 成员 *此来源属性可能会根据环境和策略而变化。
-
要将用户角色、工作区成员身份和工作区组从 Azure 同步到 Workiva,Azure 必须按照 步骤 5:管理用户角色和组中所述的特定约定,通过显示名称、自定义表达式或描述(如果策略允许)推送/拉取 SCIM 组。您可以对希望 Azure 控制的每个用户角色、工作区成员身份和工作区组成员身份完成此过程。
注意:如果策略允许 Azure 修改 Azure 安全控制组的描述属性,则可以通过描述推送/拉取 SCIM 组。这样一来,Azure 就可以在目录中保留现有的 Azure 组命名约定。为此,请将属性映射设置为:customappsso 属性 displayName 到 Microsoft Entra ID 属性 description。
- 返回 配置,在 设置 部分中,将 范围 设置为 仅同步已分配的用户和组。
- 将 配置状态 设置为 开启。
-
返回 Workiva 应用实例下的 配置 主页面,然后单击 按需配置 以测试 Workiva 中是否正确配置了用户。
注意:如果您尝试推送 Workiva 所有用户组,可能会出现错误
,因为 Azure 会尝试将该组作为组而不是用户推送。 - 测试成功后,单击 开始预配,这将启动 Azure 的初始预配周期。配置间隔设置为 40 分钟,根据人口规模和推送组的不同,可能需要一段时间。
步骤 5:管理用户角色和组
您可以通过 SCIM 组分配组织角色、工作区成员身份、工作区角色和工作区组。要使用 SCIM 组来管理成员资格和角色,您的身份提供商必须按照下面描述的特定约定,通过显示名称(或描述,如果使用 Azure 并且策略允许)推送/拉取 SCIM 组。
| 权利 | 显示名称格式 | 详细信息 |
|---|---|---|
| 组织角色 | 角色:<role name> |
被分配到同名群组的人员将被分配指定的组织角色。 例如,将用户添加到 SCIM 组“role:Org Security Admin”将授予该用户“Org Security Admin”组织角色。 |
| 工作区成员 | 工作区:<workspace name> |
分配到具有此名称的群组的人员将被添加为指定工作区的成员,并且系统将触发一封欢迎他们加入工作区的电子邮件通知。 例如,将用户添加到 SCIM 组“workspace:ABC Corp Internal Audit”将授予该用户对“ABC Corp Internal Audit”工作区的访问权限以及默认的“工作区成员”角色。 |
| 工作区角色 | 工作区:<workspace name> :角色:<workspace role name> |
被分配到具有此名称的组的人员将在指定工作区中被赋予指定的工作区角色。他们必须已经是该工作区的成员。如果他们还不是工作区成员,我们的系统将等待最多 30 秒,然后才会失败,同时等待您的身份提供商请求将用户添加到工作区。如果在时间耗尽前添加,则此操作将继续进行并成功完成。 例如,将用户添加到 SCIM 组“workspace:ABC Corp Internal Audit:role:Manager”将授予该用户在“ABC Corp Internal Audit”工作区中的“Manager”角色。 |
| 工作区组 | 工作区:<workspace name> :团体:<workspace group name> |
分配到具有此名称的组的人员将被添加到指定工作区中的指定工作区组中。他们必须已经是该工作区的成员。如果他们还不是工作区成员,我们的系统将等待最多 30 秒,然后才会失败,同时等待您的身份提供商请求将用户添加到工作区。如果在时间耗尽前添加,则此操作将继续进行并成功完成。 例如,将用户添加到 SCIM 组“workspace:ABC Corp Internal Audit:group:Editors”会将该用户添加到“ABC Corp Internal Audit”工作区中的“Editors”工作区组。 |
限制和最佳实践
在使用 SCIM 管理用户、角色和组时,请记住以下几点:
- 我们强烈建议为配置创建一个专用的 API 用户帐户,因为 SCIM 服务将代表该用户运行。活动日志中的 SCIM 操作归属于您选择的用户,并且需要具有组织用户管理员、组织工作区管理员和组织安全管理员角色。
- 不支持密码同步。
- SCIM 无法管理从其他组织邀请到组织中的用户(例如审计员或外部律师)。如果您的组织希望完全控制 Workiva 组织内的第三方用户,则需要为他们创建一个身份提供商帐户,而不是从其他组织添加用户。
- 所有用户都必须填写名字、姓氏、显示名称和电子邮件地址字段。
- 姓名栏中不允许使用变音符号。如果您的用户名称中包含这些字符,我们建议您修改映射以替换它们。
- 使用 SCIM 组将用户添加到工作区角色或工作区组时,被添加的用户必须已经是工作区的成员(有关更多详细信息,请参阅 步骤 5:管理用户角色和组)。如果他们还不是工作区成员,我们的系统将等待最多 30 秒,然后才会失败,同时等待您的身份提供商请求将用户添加到工作区。如果在时间耗尽之前添加它们,则此操作将继续进行并成功完成。
- 当需要将 20 个以上的用户批量分配到工作区角色或工作区组时,最佳实践是确保首先为用户授予工作区成员资格,然后在身份提供商的后续调用中为其分配工作区角色或工作区组。这种操作顺序确保在尝试进行其他更改(例如添加工作区角色)之前,用户已正确添加到工作区中。
错误信息
| 旧消息 | 新消息 | 错误原因 | 解决方案 |
| 未找到“{属性名称}”。 | 无效的“{属性名称}” | 提供的“{属性名称}”值无效 | 请检查“{属性名称}”的值是否正确 |
| “{属性名称}”不存在 | 无效的“{属性名称}” | 提供的“{属性名称}”值无效 | 请检查“{属性名称}”的值是否正确 |
| '{属性名称}' 已存在 | '{属性名称}' 已存在 | 提供的“{属性名称}”值已存在 | 请为“{属性名称}”输入一个唯一值 |
| '{属性名称}' 包含无效的空白字符 | “{属性名称}”包含无效的空白字符 | 提供的“{属性名称}”值不能包含空格字符 | 删除空格字符 |
| “{属性名称}”包含无效字符 | “{属性名称}”包含无效字符 | 提供的“{属性名称}”值无效 | 请输入“{属性名称}”的有效值 |
| '{属性名称}' 包含 '=',这是不允许的。 | '{属性名称}' 包含无效字符 '=' | 提供的“{属性名称}”值包含无效字符 | 请输入“{属性名称}”的有效值 |
| '{属性名称}' 过长 | '{属性名称}' 不能超过 255 个字符 | 提供的“{属性名称}”值过长 | 请输入不超过 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”。 |
| OfficePhone 太长了 | 无效的电话号码 | 提供的电话号码无效。 | 请输入有效的电话号码,或联系技术支持。 |
| 比较值无效…… | 无效的“filter”表达式 | 提供的筛选表达式无效 | 请参阅 https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.2 |
| 起始于 0 的标记的第 18 个位置出现意外字符“@”。 | 无效的“filter”表达式 | 提供的筛选表达式无效 | 请参阅 https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.2 |
| 筛选字符串意外结束 | 无效的“filter”表达式 | 提供的筛选表达式无效 | 请参阅 https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.2 |
| 未知筛选属性 | 无效的“filter”表达式 | 提供的筛选表达式无效 | 请参阅 https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.2 |
| 架构的核心属性“{ATTRIBUTE NAME}”未定义 | 未定义属性“{ATTRIBUTE NAME}”。检查模式定义。 | 该属性未在模式定义中定义。 | 检查模式定义 |
| 属性“{属性名称}”不具有多值或复杂值。 | 属性“{属性名称}”不能接受多值或复杂值。 | 该属性不能接受多值或复杂值。 | 请检查属性的模式定义,确认其预期类型。 |
| 目标值不能为空:'{属性名称}' | 必须为“{属性名称}”赋值。 | 必填字段的值未提供 | 检查所需字段的模式定义 |
| 未提供“{属性名称}”。 | 必须为“{属性名称}”赋值。 | 必填字段的值未提供 | 检查所需字段的模式定义 |
| 不能为空 | 必须为“{属性名称}”赋值。 | 必填字段的值未提供 | 检查所需字段的模式定义 |
| 校长不属于工作区成员资格 | 该用户不是工作区的成员。 | 您尝试将用户添加到属于不同工作区的组。 | 请先将用户添加到工作区。然后将用户添加到该组。 |
| 禁忌 | 您没有访问权限。联系技术支持。 | 您没有访问权限 | 请联系技术支持以获取访问权限 |
| 内部服务器错误 | 发生错误。联系技术支持。 | 我们这边出了点问题。 | 联系技术支持 |
需要协助吗?
如果您遇到任何问题或需要帮助设置身份提供商,您可以 联系支持以获得帮助。