> For the complete documentation index, see [llms.txt](https://library.zoom.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://library.zoom.com/technical-library/zh/guan-li-yuan-zhuan-qu/account-and-endpoint-management/scim-guide.md). # 适用于 Entra ID 和 Okta 的 SCIM 实地指南 在 Entra ID 或 Okta 与 Zoom 之间创建自定义 SCIM 映射的指南 ## 概述 Zoom 的 SCIM2 API 公开了一个庞大的用户属性目录，这些属性控制许可、产品权益、角色、区域以及按服务的配置。Microsoft Entra ID 和 Okta 的开箱即用配置集成只映射了这些属性中的一小部分——足以创建、更新和停用用户，但不足以为 Zoom Phone 站点、呼叫中心套餐、Revenue Accelerator 角色，或 Zoom 支持的其他数十种属性进行配置。 本指南介绍一种可重复的方法，用于添加 *任意* Zoom SCIM 属性到你的配置配置中。它并不是孤立地记录某一个属性，而是解释其底层模型，使管理员能够在 Zoom 的 SCIM2 API 参考中查找某个属性，并独立进行配置，而无需等待某篇特定产品的文章发布。 ### 如何使用本指南 先阅读以下开头的简介 [**了解 SCIM 属性**](#understanding-scim-attributes) 首先阅读这些内容，以及其后的各部分——前置条件、目录数据、参考场景和 Zoom 端验证。这些内容适用于你使用的任何身份提供商（IdP）。然后根据你使用的是哪一种，继续阅读 Microsoft Entra ID 或 Okta 部分。这两部分都从第一个配置步骤一直完整覆盖到验证和示例演练；你无需在它们之间来回切换。 对于位于本指南之下的基础 SSO 和 SCIM 概念，请参阅 [SSO 使用指南](https://library.zoom.com/admin-corner/account-and-endpoint-management/sso-field-guide)，以及 [适用于 Entra ID 的 Zoom SSO 和预配文章](https://support.zoom.com/hc/en/article?id=zm_kb\&sysparm_article=KB0064121)，以及 [适用于 Okta 的 Zoom SSO 文章](https://support.zoom.com/hc/en/article?id=zm_kb\&sysparm_article=KB0063256). {% hint style="danger" %} **警告** 配置错误的预配会影响现有用户，包括移除已在使用中的许可证。在应用到实际用户群之前，请针对单个测试用户验证每一项更改。 {% endhint %} ### **使用 SCIM 的先决条件** 本部分中的所有内容均适用于任何身份提供商。请在继续查看针对身份提供商的具体说明之前先阅读此处。 #### 两种身份提供商通用的要求 * 具有已获批准的商业版、教育或企业版 Zoom 账户 [实名网址](https://support.zoom.com/hc/en/article?id=zm_kb\&sysparm_article=KB0061540) * Zoom 账户所有者或管理员权限 * [单点登录](https://support.zoom.com/hc/en/article?id=zm_kb\&sysparm_article=KB0060673) 已在 Zoom 账户上启用 * 一个 [已验证的关联域名](https://support.zoom.com/hc/en/article?id=zm_kb\&sysparm_article=KB0066259) 在 Zoom 账户上，与正在配置的用户的电子邮件域名相匹配 * 身份提供方与 Zoom 之间已建立 SCIM 预配 * 正在分配的 Zoom 许可证、计划、附加组件或配置对象必须已存在并在 Zoom 账户上在线可用 各身份提供方特定的要求列在各自章节的开头。 #### 两种身份提供方共有的限制 * SCIM 只会分配现有的权益；它不能创建其所引用的对象。请参见该章节 [**在尝试高级映射之前，必须先存在 Zoom 端对象，SCIM 才能引用它们**](#before-attempting-advanced-mapping-zoom-side-objects-must-exist-before-scim-can-reference-them) 如下。 * 某些属性每个用户只接受一个值。Zoom Phone 通话套餐就是其中一个例子——诸如 Customer Engagement Pack 之类的附加组件包不能通过 SCIM 进行配置。 * 该 `用户类型` 属性已由 Zoom 文档注明为计划弃用。 ## **简介** ### **了解 SCIM 属性** 了解 Zoom SCIM 属性构成方式的管理员可以配置 Zoom 支持的任何属性。遵循某个配方的管理员只能配置该配方所描述的属性。本节介绍其构成。将属性映射到数据源的内容将在后面的身份提供方章节中介绍。 #### 每个属性都有一个命名空间、一个名称、一个数据类型和一个允许的值 让我们从一个完整、可用的示例开始。以下是用于将用户分配到 Zoom Phone 站点的标识符： ``` urn:ietf:params:scim:schemas:extension:zoom:1.0:用户:zoomPhoneSite ``` 此属性有四个属性在起作用。其中两个在上一行可见。另外两个来自 API 参考，并会在稍后输入到你的身份提供商中的其他位置。就我们当前的目的而言，我们关注其中两项：该 **命名空间** 和 **名称**.
属性从示例中提取的它的作用
命名空间urn:ietf:params:scim:schemas:extension:zoom:1.0:用户告诉 Zoom 该设置属于哪个模式，并作为几乎每个 Zoom 产品和许可属性的共享基础。作为标识符的前半部分传递给 Zoom。
名称zoomPhoneSite标识正在写入的具体 Zoom 设置——此处为用户的 Zoom Phone 站点。作为标识符的后半部分传递给 Zoom。区分大小写。
数据类型字符串告诉你的身份提供商该属性包含何种值，以便正确存储和格式化。不会作为标识符的一部分传递；而是单独声明为 类型 在 Entra ID 中，或 数据类型 在 Okta 中。
允许的值LON-01，一个 Zoom Phone 站点名称实际应用于用户的设置。某些属性为自由文本，其他属性则为固定集合—— 基础版, 高级版，或 精英版 例如用于 Zoom 呼叫中心。在配置时传递给 Zoom，由映射而不是标识符提供。
{% hint style="danger" %} **警告** Zoom 发布了不止一个用户分机命名空间。产品配置和许可属性使用 `urn:ietf:params:scim:schemas:extension:zoom:1.0:用户`，这是本指南始终使用的命名空间。标准企业版字段，例如 `部门`, `经理`，和 `成本中心` 使用 `urn:ietf:params:scim:schemas:extension:企业版:2.0:用户`。第三个， `urn:us:zoom:scim:schemas:extension:1.0:ZoomUser`，携带在 API 响应中返回的登录类型信息，而不是在配置过程中配置的。基于错误命名空间构建的属性会被你的身份提供商接受，并被 Zoom 静默忽略。 {% endhint %} #### 在 SCIM2 API 参考中找到你需要的属性 该 [SCIM2 API 参考](https://developers.zoom.us/docs/api/scim2/#tag/user/post/scim2/Users) 是 Zoom 在预配期间接受的所有内容的权威列表。两个操作很重要： **创建一个用户** 和 **更新一个用户**. 主要基于 **更新一个用户**。创建每个人只发生一次，但属性更改会持续发生——办公室搬迁、计划更改、角色更改、离职人员——因此，配置在一段时间内实际执行的大部分工作都是更新。 **更新一个用户** 还记录了删除值，该 **创建一个用户** 没有理由包含，例如设置 `zoomPhoneCallingPlan` 到 `-1` 以从用户中移除所有通话套餐。 要查找某个属性： * 打开 SCIM2 API 参考并转到 **更新一个用户**. * 在请求正文中，找到 `urn:ietf:params:scim:schemas:extension:zoom:1.0:用户` 对象。本文档中涉及的每个属性都列在其中。 * 按名称找到你的属性，并录制其 **数据类型** 以及其 **允许的值**. * 阅读其旁边的描述。描述包含你无法从属性名称推断出的行为—— `zoomPhoneExtNumber` 设置为 `0` 会触发自动分机分配， `zoomPhoneCallingPlan` 设置为 `-1` 会移除所有通话套餐，并且 `zoomPhoneNumber` 必须引用一个已在 Zoom 账户中取消分配的号码。 #### 组装标识符：父级、冒号、子级 其中列出的所有内容 `urn:ietf:params:scim:schemas:extension:zoom:1.0:用户` 对象是一个 **子级** 的子级。该对象本身是 **父级**。构建标识符意味着先命名父级，添加一个冒号，然后添加子级： ``` 父级 urn:ietf:params:scim:schemas:extension:zoom:1.0:用户 冒号 : 子级 zoomPhoneSite 标识符 urn:ietf:params:scim:schemas:extension:zoom:1.0:用户:zoomPhoneSite ``` 这就是全部构造。无需向 Zoom 请求查找表，也无需生成任何内容——标识符就是你已经拥有的两个东西，用冒号连接起来。 #### 父级保持不变；只更改子级 因为父级是固定的，配置第二个、第五个或第十五个属性只是同样的操作，只是在后面追加了不同的子级： ``` 基础（父级） urn:ietf:params:scim:schemas:extension:zoom:1.0:用户 Zoom Phone 站点 urn:ietf:params:scim:schemas:extension:zoom:1.0:用户:zoomPhoneSite Zoom Phone 号码 urn:ietf:params:scim:schemas:extension:zoom:1.0:用户:zoomPhoneNumber Zoom Phone 分机 urn:ietf:params:scim:schemas:extension:zoom:1.0:User:zoomPhoneExtNumber Zoom Phone 通话套餐 urn:ietf:params:scim:schemas:extension:zoom:1.0:用户:zoomPhoneCallingPlan ``` 同一个父级承载着其他所有 Zoom 产品。产品变化时，构造本身不会有任何变化： ``` 呼叫中心 软件包 urn:ietf:params:scim:schemas:extension:zoom:1.0:用户:zoomContactCenterPackage 收入加速器 角色 urn:ietf:params:scim:schemas:extension:zoom:1.0:User:zoomRevenueAcceleratorRole Workplace 套件 urn:ietf:params:scim:schemas:extension:zoom:1.0:用户:zoomWorkplace Zoom Docs urn:ietf:params:scim:schemas:extension:zoom:1.0:用户:zoomDocs ``` 因此，您只需学习一次父项。从那以后，配置新属性就只意味着在 API 参考中查找三项内容：子项名称、其数据类型以及其允许值。 如果你能组装好父级和子级，那么这个配置中最难的部分就已经过去了。接下来剩下的就是告诉你的身份提供商每个值应该来自哪里——这将在后面的 Entra ID 和 Okta 部分中介绍——以及决定先处理哪些属性，这将在下一步介绍。 #### 两种映射：基础版和高级版 并非每个属性都承担相同的风险，因此在配置任何内容之前，先对它们进行排序是值得的。 本指南借用了这些术语 **基础版** 和 **高级** 来自于 [SSO 使用指南](https://library.zoom.com/admin-corner/account-and-endpoint-management/sso-field-guide)，它在 SAML 响应映射中也划出了同样的界限。这些术语描述的是 **Zoom 接收到值时会对其做什么**，而不是该属性有多难配置。从机制上看，这两者是完全相同的：二者都记录在同一个 **更新一个用户** 请求正文中，二者都采用相同的“父-冒号-子”结构构建，并且都通过 Entra ID 和 Okta 中相同的步骤进行声明和映射。 * **基础版映射** 将文本写入用户的个人资料。Zoom 会按原样保存该值，且从不将其与任何内容进行比对。 * **高级映射** 向账户提出声明。Zoom 取该值并查找匹配的对象，或在已购买的方案中查找一个空闲席位——而该查找可能会失败。
基础版映射高级映射
值是什么存储在用户个人资料中的文本Zoom 中某个对象的指针，或对已购买席位的声明
示例部门, 标题, 成本中心zoomPhoneSite, zoomContactCenterRole, zoomWorkplace
父级顶层，或企业版扩展Zoom 扩展
Zoom 中的前置条件无对象必须存在，或者座位必须空闲
如果值不正确个人资料上会显示错误文本该属性会被拒绝，或者被静默忽略
这种区别会带来两个实际决定。它决定 **你必须先在 Zoom 中构建什么** —— 对基础版映射来说几乎没有；对高级版来说可能很多——并且它决定 **一个错误的代价**。错误的部门只是个人资料中的一个外观错误。错误的站点名称或不可用的许可证席位会让用户没有可用的电话，或者没有他们受聘使用的产品；在实际部署中，还可能从已经拥有该权限的人那里剥夺该权限。 这种后果上的差异，就是下文将二者分开处理的原因。 #### 基础版映射：个人资料信息 基础版映射会填充用户 Zoom 个人资料中的描述性字段。Zoom 会按发送时的原样存储每个值，并且从不针对现有对象进行验证，因此在 Zoom 中事先无需创建任何内容，若某个值有误，也不会破坏任何东西。 **核心身份字段通常已经映射好了。** `用户名`, `name.givenName`, `name.familyName`, `显示名称`，和 `电子邮件` 位于请求正文的顶层，完全没有父级，而 Entra ID 和 Okta 集成都能开箱即用地将它们映射出来。请验证它们，而不是重新构建它们。 `标题`, `电话号码`，和 `区域设置` 也属于顶级，但可能需要添加。 **企业版字段使用第二个父级。** 构造不会更改——只有父级会更改： ``` 基础（父级） urn:ietf:params:scim:schemas:extension:企业版:2.0:用户 部门 urn:ietf:params:scim:schemas:extension:企业版:2.0:用户:department 成本中心 urn:ietf:params:scim:schemas:extension:企业版:2.0:用户:costCenter 员工编号 urn:ietf:params:scim:schemas:extension:企业版:2.0:用户:员工编号 组织 urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:organization 经理 urn:ietf:params:scim:schemas:extension:企业版:2.0:用户:manager ``` 通过 SCIM 填充部门和成本中心不再需要 SAML 映射。 {% hint style="info" %} **推荐** 先映射一个基础属性—— `部门` 是一个不错的候选项，并作为 **场景 0** 在参考场景中——并在 Zoom 扩展下配置任何内容之前，先为单个测试用户端到端运行它。A `部门` 在 Zoom 个人资料中正确显示的值证明了模式声明、映射、范围以及你阅读配置日志的能力。接下来每个高级属性的不同之处仅在于它指向的对象，而不在于它的配置方式。 {% endhint %} #### 高级映射：产品配置和授权 高级映射会为用户可执行的操作分配相应内容：一个 Zoom Phone 站点和通话套餐、一个呼叫中心角色和软件包、一个 Workplace 套件、一个 Revenue Accelerator 分段。这些属性都位于本指南中使用的 Zoom 扩展父级下。 真正重要的区别在于，这些值并不是存储起来的——它们是 **已解析**. Zoom 会获取你发送的值，并查找匹配的对象或一个在线席位。基础映射会将文本写入个人资料，而高级映射则会针对账户的配置和库存提出声明，而这个声明可能会失败。 这就是为什么本指南专门用整整一节来说明前提条件。每个高级属性都依赖于先前已在 Zoom Web门户中创建或购买的内容，而这些失败模式远没有拼错的职位名称那样宽容。 #### 每种配置共有的三层 无论使用哪种属性或哪家身份提供商，工作都相同，都是这三层。不同的只是每个控件所在的位置。
层用途Microsoft Entra IDOkta
1. 声明将该属性告知身份提供商，使其在 Zoom 应用程序中存在，从而可作为映射目标使用。步骤 1步骤 1
2. 映射定义值的来源。步骤 2步骤 2–3
3. 范围确定该配置适用于哪些用户以及何时运行。步骤 3–5步骤 4–5
一旦理解这种模式，添加第五个或第十五个属性只是同样三层的重复，而不是新项目。 #### Entra 和 Okta 在值的来源方面有所不同 这是两条路径之间最关键的架构差异，它解释了为什么同样的业务需求在 Entra 和 Okta 中会产生不同的配置。 * **Entra ID 仅从用户对象属性中获取值。** 值必须来自用户上的某个字段——现有目录字段或专门打造的扩展属性。目录值与 Zoom 值不是同一字符串时，需要使用表达式在两者之间进行转换。 * **Okta 可从用户资料或群组分配中获取值。** 使用以下方式声明属性： **属性类型：群组** 可将值一次性设置在群组上，并由每位成员继承。当配置遵循组织结构时，这可完全消除对转换逻辑的需求。 这两种方法都不是绝对更好，但会导致不同的配置。 ### **Zoom 端预配置要求** #### 在尝试高级映射之前，必须先存在 Zoom 端对象，SCIM 才能引用它们 SCIM 是一种分配机制，而不是创建机制——它将用户连接到 Zoom 账户中已存在的配置，并且它 **无法** 代用户构建该配置。 高级映射属性中相当大一部分是 **引用项**：你发送的值应解析为 Zoom 中已存在的对象——站点、角色、模板、已购买的软件包、特定号码或分机。它们都遵循同一规则： > 如果属性命名了某个对象，那么该对象必须已经存在，名称必须与发送内容完全一致，并且——当它依赖有限资源池时——必须还有未使用的容量。 当被引用的对象不存在时，SCIM 既不会创建它，也不会排队请求。该属性要么直接失败，错误会返回到分配日志中，要么被静默丢弃——Zoom 接受负载，不执行任何操作，并报告成功。 下文各节将按产品列出前置条件，并附上构建每一项所需的导航路径和支持文章。先阅读账户级说明，再查看你计划分配的每个产品对应的章节。 #### 在任何产品开始分配之前，账户级前置条件都适用 本指南开头列出的账户要求——实名网址、SSO、SCIM 授权以及已验证的关联域——是后续每个属性的前置条件。这四项都在以下位置配置： **高级** → **安全** / **单点登录** / **关联域**；参见 [Zoom + Microsoft Entra ID SSO/SCIM 配置](https://support.zoom.com/hc/en/article?id=zm_kb\&sysparm_article=KB0064121). 另外还有两点值得明确说明： * **购买席位不等于分配席位。** SCIM 负责执行分配，但席位必须先存在。参见 [为用户分配或移除 Zoom 许可证](https://support.zoom.com/hc/en/article?id=zm_kb\&sysparm_article=KB0064911). * **席位必须属于所请求的确切软件包。** 当该特定软件包没有空余席位时，发送许可证属性也会失败，即使账户中的其他软件包显示仍有剩余容量。 #### Zoom Phone Zoom Phone 拥有最多的一组引用属性，因为电话用户是由若干预购或预构建的基础设施组件组装而成。 | 属性 | 必须已存在的内容 | 如何创建 | | -------------------------------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Zoom Phone 许可证本身 | 一个可用的 Zoom Phone 席位——在下方任何内容可附加之前所需的前置授权。 | 请提前购买。参见 [购买并分配 Zoom Phone 许可证](https://support.zoom.com/hc/en/article?id=zm_kb\&sysparm_article=KB0077929). | | `zoomPhoneSite` | 站点，其名称必须与发送的值完全一致。省略该属性会分配账户的主站点，而在启用多个站点后，主站点默认已存在。 | 管理中心 → 产品配置 → 电话系统 → 公司信息 → **添加站点**，或 **导入** 用于批量创建。参见 [管理多个站点](https://support.zoom.com/hc/en/article?id=zm_kb\&sysparm_article=KB0069716). | | `zoomPhoneNumber` | 该号码已购买或转入账户，且当前未分配。已被其他用户、呼叫队列或自动接线员占用的号码不能重复使用。 | 管理中心 → 产品配置 → 号码 → 电话号码。请在此处购买或转入，并让目标号码保持未分配状态，以便 SCIM 可以认领它。参见 [使用号码管理来管理电话号码](https://support.zoom.com/hc/en/article?id=zm_kb\&sysparm_article=KB0074457) 和 [管理电话号码](https://support.zoom.com/hc/en/article?id=zm_kb\&sysparm_article=KB0060212). | | `zoomPhoneExtNumber` (仅限特定值) | 一个 3–6 位且尚未使用的分机号码。发送以下内容时不需要 `0`，这会将分配委托给 Zoom。 | 管理中心 → 产品配置 → 电话系统 → 用户与房间 → 选择持有分机的对象 → **个人资料** → **分机号码** → **编辑**。参见 [更改电话用户设置](https://support.zoom.com/hc/en/article?id=zm_kb\&sysparm_article=KB0069338). | | `zoomPhoneCallingPlan` | 通过其准确套餐代码引用的通话套餐，已购买且具有可用容量。 | 请提前购买。参见 [购买并分配 Zoom Phone 许可证](https://support.zoom.com/hc/en/article?id=zm_kb\&sysparm_article=KB0077929) 和 [管理电话用户](https://support.zoom.com/hc/en/article?id=zm_kb\&sysparm_article=KB0069309)。套餐代码列于 [Zoom Phone 通话套餐参考](https://developers.zoom.us/docs/api/references/phone-calling-plans/)，或者作为 `类型` 由 [列出通话套餐](https://developers.zoom.us/docs/api/references/phone-calling-plans/) API 一并返回，以及可用席位数量。 | | `zoomPhoneCallingPlanSubscription` (仅限多订阅账户) | 当账户针对同一套餐拥有多个订阅时，套餐应从中提取的具体订阅。 | 套餐与账单 → 订阅管理。 | **分机池在各类对象之间共享，不仅限于用户。** 呼叫队列、自动接线员、共享线路组和公共区域电话都会从同一范围消耗分机。这是“分机已在使用中”失败最常见的原因，因为当管理员只检查用户列表时，分机看起来是空闲的。 **转入完成之前，已转入的号码不可分配。** 该号码必须既存在于账户中，又处于未分配状态；发起转入并不满足这两个条件。 **站点是最常见的阻碍** 因为创建站点本身也有要求。站点地址会根据真实世界地址数据库进行验证，因为它们支撑紧急通话服务——虚构的地址和邮政编码组合会因验证错误而被拒绝。批量导入站点时，自动接线员列期望的值是 `是` 而不是界面中显示的标签文本，并且来电显示名称主要适用于美国和加拿大；如果它会导致验证失败，可以留空。 #### Zoom 呼叫中心 呼叫中心的分配由角色和模板驱动。单个属性必须解析为现有的呼叫中心对象，而模板承载那些没有专属 SCIM 属性的设置。 | 属性 | 必须已存在的内容 | 如何创建 | | ------------------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `zoomContactCenterPackage` | 该软件包—— `基础版`, `高级版`，或 `精英版` ——购买时附带未使用席位。 | 请提前购买；Premium 可能需要先联系 Zoom 支持购买额外软件包。参见 [更改 Zoom 呼叫中心用户设置](https://support.zoom.com/hc/en/article?id=zm_kb\&sysparm_article=KB0060874). | | `zoomContactCenterAddonsPlan` | 该附加组件套餐，已购买且具备容量。 | 提前购买；账户方案和账单信息。 | | `zoomContactCenterRole` | 角色需精确命名，可为标准或自定义。省略它将分配默认的 Agent 角色，该角色默认存在。 | 呼叫中心管理 → 角色 → **添加** → 配置权限 → **保存**。参见 [管理 Zoom 呼叫中心角色](https://support.zoom.com/hc/en/article?id=zm_kb\&sysparm_article=KB0061941). | | `zoomContactCenterRegion` | 区域。省略它将分配账户的主区域，该区域必须先配置。 | 呼叫中心管理 → 首选项 → 区域 → **添加区域** → 输入名称并选择一个 SIP 区域 → **添加**。参见 [管理 Zoom 呼叫中心区域](https://support.zoom.com/hc/en/article?id=zm_kb\&sysparm_article=KB0057668). | | `zoomContactCenterUserTemplate` | 用户模板，需精确命名。添加型模板在创建用户时应用；更新型模板在更新时应用。 | 呼叫中心管理 → 用户 → 模板 → **添加模板** → 选择 **添加** → 配置角色、套餐、队列和技能 → **添加**。参见 [管理 Zoom 呼叫中心用户设置模板](https://support.zoom.com/hc/en/article?id=zm_kb\&sysparm_article=KB0077757). | {% hint style="danger" %} **警告** 呼叫中心区域功能必须由 Zoom 支持启用后才能创建区域，并且每个用户都只属于一个区域。由于这属于支持请求，而不是自助切换选项，如果计划部署多区域，请尽早提出。 {% endhint %} **收件箱、队列和技能没有 SCIM 属性。** 要为它们进行预配，请先在呼叫中心管理中预先创建它们，将它们附加到用户模板，并通过 `zoomContactCenterUserTemplate`. 因此，它们成为 *模板* 而不是个别用户的——这也使得模板在这些要求变化时成为唯一需要维护的对象。
对象如何创建
队列呼叫中心管理 → 队列 → 添加队列 → 名称、频道、坐席 → 保存。参见 管理 Zoom 呼叫中心队列.
技能呼叫中心管理 → 技能 → 选择一个类别 → 添加技能 → 名称 → 添加。参见 管理技能和技能类别.
收件箱呼叫中心管理 → 收件箱 → 添加收件箱。参见 管理 Zoom 呼叫中心收件箱.
**如果同时提供模板和单个属性，则以单个值为准。** 与模板一起发送 `zoomContactCenterRole` 这意味着角色属性会覆盖模板的角色设置，因此所引用的角色和模板都必须存在。 #### Zoom Revenue Accelerator | 属性 | 必须已存在的内容 | 如何创建 | | ------------------------------------------------------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `zoomRevenueAcceleratorPlan` 和 `zoomRevenueAcceleratorSubscription` | 已购买的 ZRA 方案或包含一个在线席位的订阅。 | 提前购买；账户方案和账单信息。 | | `zoomRevenueAcceleratorRole` | 角色，标准或自定义——例如 `销售经理` ——名称必须完全一致。 | 用户管理 → 角色 → **收入加速器** 选项卡 → **+ 添加角色** → 名称和描述 → **添加** → 配置权限 → **保存更改**。参见 [使用 Zoom Revenue Accelerator 角色管理](https://support.zoom.com/hc/en/article?id=zm_kb\&sysparm_article=KB0059285). | | `zoomRevenueAcceleratorSegment` | 该用户所属的细分市场。 | 收入加速器管理员设置。 | | `zoomRevenueAcceleratorRegion` | 区域——例如， `美国`. | 收入加速器管理员设置。 | #### Zoom Workplace 许可证和账户角色 除上述三种产品外，标准用户录制还包含遵循相同规则的角色和许可证引用。 | 属性 | 必须已存在的内容 | 如何创建 | | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `roles[]` (`值` / `显示`) | 账户角色，名称必须完全一致。角色由 SCIM 引用，绝不会由其创建。 | 用户管理 → 角色 → **添加角色** → 名称和描述 → 配置权限。请参阅 [使用角色管理](https://support.zoom.com/hc/en/article?id=zm_kb\&sysparm_article=KB0064983). | | `zoomWorkplace` 以及其他许可证或附加组件属性——白板、Scheduler、Clips Plus、翻译字幕、劳动力管理、质量管理、合规性管理、CX Insights、AI 销售助手，以及它们的 `...订阅` 对应项 | 相应的捆绑包或附加组件，购买时带有未使用的席位。 | 套餐和账单 → 套餐管理 → 编辑套餐 → 增加许可证数量。请参阅 [升级您的账户和附加组件](https://support.zoom.com/hc/en/article?id=zm_kb\&sysparm_article=KB0063375). | | `loginType` (`sso` / `workEmail`），位于 `urn:us:zoom:scim:schemas:extension:1.0:ZoomUser` | 为 SSO 登录类型在账户上配置的 SSO。 | 高级 → [单点登录](https://support.zoom.com/hc/en/article?id=zm_kb\&sysparm_article=KB0064121). | 对于许可证或附加组件属性，没有可命名的对象，但前提条件的实际效果相同：如果该特定池中没有可用席位，分配将失败。 #### 没有前提条件的属性 每个基础映射属性都符合条件，如下文所述 **基础版映射：个人资料信息** ——Zoom 会逐字存储这些值，且绝不会根据现有对象验证它们。Zoom 扩展下的两个属性也具有相同的行为： * **自动委派的值** —— `zoomPhoneExtNumber` 发送为 `0`，其中 Zoom 会自行分配扩展。 * **账户自定义属性** ——该 `{customAttribute}` 字段，其中保存您发送的任何字符串。 **默认引用** 属于一种中间情况：省略 `zoomPhoneSite`, `zoomContactCenterRole`，或 `zoomContactCenterRegion` 则分别回退到主站点、默认 Agent 角色和主区域。这些默认项本身必须存在，而它们默认情况下确实存在。 **群组是一个部分例外。** 在启用群组预配时，SCIM 会使用源群组中键入的名称原样创建一个尚不存在的 Zoom 群组。它不会将任何产品配置应用到该群组——该群组创建后只包含成员，别无其他。Zoom Phone 策略、呼叫权限以及其他群组级设置，在群组出现后仍必须在 用户管理 → 群组管理 下进行配置。 {% hint style="info" %} **推荐** 应将 Zoom 侧搭建视为一个前置阶段，并进行单独签核，在属性映射工作开始前完成并验证。站点、号码、套餐、角色和模板往往由不同于身份提供程序配置的团队负责，而在预配测试中发现某个对象缺失的成本，远高于事先确认其存在的成本。 {% endhint %} ### **准备您的目录数据** SCIM 会传输源中包含的任何内容。它不会验证、规范化或更正。在映射任何属性之前，请确认目标源的三件事： * **它对范围内的每个用户都已填充。** 未填充的字段不会发送任何内容，或者会发送已配置的默认值。 * **其值在格式和大小写方面保持一致。** 两个身份提供程序中的比较逻辑都必须精确匹配。 * **其值与 Zoom 预期的值完全一致。** Zoom 不会对站点名称、角色名称或计划值进行模糊匹配。 当现有字段无法满足这三个条件时，一个专门打造、并为此次集成有意填充的属性，比改用一个其他系统也会写入的字段更可持续。 {% hint style="info" %} **推荐** 在修改身份提供商配置之前，先确定唯一事实来源。大多数失败的 SCIM 部署，本质上都是以预配问题形式表现出来的目录数据问题。 {% endhint %} ### **参考场景** 本指南通篇使用四个场景。无论身份提供商如何，它们的业务需求和 Zoom 端先决条件都相同，因此这里统一定义。每个特定于身份提供商的章节结尾都会展示如何在该平台上实现全部四个场景。 #### 场景 0：部门，作为第一个基础映射 用户的部门应显示在其 Zoom 个人资料中，数据来源于目录。这里介绍的是前文建议的基础映射，作为第一个端到端测试；之所以将其列在这里，是为了让该流程在两个身份提供商部分都能走一遍。 **Zoom 端先决条件。** 无。Zoom 会按发送的原样存储该值，并且从不将其与现有对象进行验证。 **属性。** 请注意，父级与下面三个场景不同—— `部门` 位于企业版扩展下，而不是 Zoom 扩展下。 | 属性 | 类型 | 备注 | | -------------------------------------------------------------- | --- | -------------------------------------------- | | `urn:ietf:params:scim:schemas:extension:企业版:2.0:用户:department` | 字符串 | 自由文本。两个身份提供商都已经包含一个 `部门` 用户资料上的字段，因此无需新增源属性。 | **为什么从这里开始。** 一个在 Zoom 资料上正确显示的部门值，证明了架构声明、映射、范围，以及你读取配置日志的能力——而不会让许可证或电话配置面临风险。下面的每个高级场景只是在属性指向的对象上有所不同。 **先检查它是否已经映射。** 默认映射在 Entra ID 和 Okta 之间有所不同，并且会随着两家供应商更新其 Zoom 集成而更改。请查看下方现有列表中的 **配置** → **映射** 在 Entra 中，或 **Zoom 属性映射** 与 **显示未映射的属性** 在 Okta 中启用。如果 `部门` 已映射，请予以验证，而不是声明为重复项——如果您希望某个属性从头开始配置， `成本中心`, `组织`，和 `employeeNumber` 位于同一父级下并表现一致。 #### 场景 1：Zoom Phone 站点和自动分机号码分配 应根据用户所在的办公室将用户分配到正确的 Zoom Phone 站点，并在无需管理员干预的情况下为其分配分机号码。 **Zoom 侧前提条件** 这些站点必须已存在。在以下位置创建它们： **管理员中心** → **产品配置** → **电话系统** → **公司信息** → **添加站点**，或者通过批量方式使用 **导入**。站点地址会根据真实世界地址数据库进行验证，因为它们支持紧急通话服务，所以虚构的地址和邮政编码组合将无法通过验证。 **属性。** 两者都采用命名空间 `urn:ietf:params:scim:schemas:extension:zoom:1.0:用户:` 后跟名称。 | 属性 | 类型 | 备注 | | -------------------- | --- | ----------------- | | `zoomPhoneSite` | 字符串 | 必须与 Zoom站点名称逐字符匹配 | | `zoomPhoneExtNumber` | 字符串 | `0` 触发自动分配 | **为什么该值 `0` 重要。** Zoom 是唯一知道哪些分机已在使用中的系统——包括分配给呼叫队列和自动接待员而不是用户的分机。将分配委托给 Zoom 可消除一整类配置失败。在迁移期间，改为从目录中获取分机号是合适的，因为保留现有分机号码很重要，但映射应切换为 `0` 一旦迁移完成，以便未来加入者不会依赖目录数据被无限期维护。 {% hint style="info" %} **注意** Zoom Phone 账户上的默认站点通常名称正是 `主站点`，可见于 **管理员中心** → **产品配置** → **电话系统** → **公司信息**。在依赖它之前，请先确认该特定账户上的名称，因为它可以被重命名。 {% endhint %} #### 场景 2：按国家而异的 Zoom Phone 通话套餐 一家跨国组织已购买独立的 Zoom Phone 通话套餐，并需要每位用户收到与其国家相匹配的套餐。 **Zoom 端先决条件。** 这些通话套餐必须已购买并在账户中在线可用。套餐值记录在 [Zoom Phone 通话套餐参考](https://developers.zoom.us/docs/api/references/phone-calling-plans/). **属性。** `zoomPhoneCallingPlan` （字符串）。 **如何获取正确的套餐代码。** `zoomPhoneCallingPlan` 它使用数字计划代码，而不是计划名称。获取它最可靠的方式是 [列出通话套餐](https://developers.zoom.us/docs/api/references/phone-calling-plans/) API，它会返回每个计划的 `名称`，其 `类型` ——你映射的代码——以及其 `已订阅的` 和 `在线` 席位数。因此，一次呼叫就能确认计划存在，为你提供要发送的值，并验证是否有容量来分配它。 Zoom Web门户只显示名称，从不显示代码，因此仅凭门户工作的管理员必须使用 [Zoom Phone 通话套餐参考](https://developers.zoom.us/docs/api/references/phone-calling-plans/) ——例如， `UNLIMITED_PLAN_US_CA` 是 `200` 和 `UNLIMITED_PLAN_GB_IE` 是 `202`. 该参考文档列出的是常量名称，而不是门户中的措辞，因此请根据套餐特征——地区，以及按量计费与无限套餐——来确认是否匹配，而不是根据确切文本。 另外，Zoom 的 SCIM2 API 参考文档显示了一个账单计划名称，例如 `phone_calling_usca_monthly_unlimited` 出现在其示例负载中。该标识符用于 *购买* 一个订阅，而不是将计划分配给用户。如果您需要指定某个计划所依赖的是哪个订阅，这应填写在 `zoomPhoneCallingPlanSubscription`. **为什么 `-1` 用作回退值。** SCIM2 参考文档 `-1` 作为移除所有呼叫计划的值。将其用于未匹配的用户会产生一个确定且可见的结果——未分配计划——而不是完全不传值所带来的歧义。它还提供了一种无需删除用户即可取消分配呼叫权益的简洁方式。 #### 场景 3：Zoom 呼叫中心软件包、角色和区域 呼叫中心坐席应在适职时分配正确的 ZCC 软件包和角色，而不是事后手动配置。此场景展示了该方法与产品无关——流程本身没有变化，变化的只有属性名称和允许的值。 | 属性 | 类型 | 允许的值 | | -------------------------- | --- | --------------------------- | | `zoomContactCenterPackage` | 字符串 | `基础版`, `高级版`, `精英版` | | `zoomContactCenterRole` | 字符串 | 任何 ZCC 角色名称。默认值为 `坐席` 如果省略。 | | `zoomContactCenterRegion` | 字符串 | 任何已配置的 ZCC 区域。若省略，则默认为主区域。 | **关于有意省略属性。** 离开 `zoomContactCenterRegion` 在单区域部署中保持未映射，因为 Zoom 文档中记载的默认值已经是正确的。与其映射一个默认值本就正确的属性，不如不映射它——每一次映射都会带来维护负担。 **操作说明。** SCIM2 参考文档也说明了 `zoomContactCenterUserTemplate`，这将应用一个预先构建的 ZCC 模板。添加类型模板在用户创建时应用，更新类型模板在更新时应用；当同一请求中同时提供模板和单个属性值时，单个值具有优先级。对于 ZCC 配置足够复杂、以至于在许多个别属性映射之间维护它会变得难以处理的情况，模板值得考虑。 ### **Zoom侧验证和常见错误** 每个身份提供商都有自己的日志，在各自身份提供商的第 6 步中有说明。下面的 Zoom 端日志对两者都相同，并且是 Zoom 实际收到内容的最终录制。 #### Zoom App Marketplace 呼叫日志 显示完整的请求和响应交换 1. 以账户所有者身份登录 Zoom Web门户。 2. 导航到 [**Zoom App Marketplace**](https://marketplace.zoom.us/) → **管理** → **账户上的应用**. 3. 选择代表身份提供者连接的应用程序。对于 Entra，这通常命名为 **Azure 身份** 或类似内容。 4. 打开 **呼叫日志** 选项卡。 5. 使用 **按端点搜索**，或使用日期范围、方法和状态筛选器来定位相关呼叫。 6. 选择该行以展开它。 7. 查看 `请求正文` 以准确查看发送了什么，并且 `响应` 以准确查看 Zoom 返回了什么，包括生成的 Zoom 用户 ID， `HTTP 状态`以及结果属性集。 Zoom 保留最近 100 条 API 请求日志，因此应及时调查故障，而不要等到后续更多配置活动将其覆盖。 #### 常见的配置错误及其原因
代码消息原因及解决方法
400账户尚未启用单点登录。SSO 是 SCIM 的前提条件。请先在 Zoom 账户上启用并配置 SSO。
400用户处于不活跃或已锁定状态。目标 Zoom 用户在当前状态下无法更新。请在 Zoom Web门户中解决账户状态问题。
403由于权限不足，请求被拒绝：“用户:编辑”。SCIM 连接背后的凭据缺少所需的作用域。请使用所有者或管理员账户重新授权该连接。
404用户不存在。身份提供商未将该用户对应到现有 Zoom 用户。请验证匹配属性和用户名格式。
409电子邮件域名与该账户关联的域名不匹配。该用户的电子邮件域名未与 Zoom 账户关联。请先关联并验证该域名，然后再进行预配。
409无法添加付费用户。所请求类型的许可证没有可在线使用。请释放该账户的容量，或将该用户预配为基础版。
409无法使用 [bundle name] 创建更多用户。该特定捆绑包没有剩余席位。适用于 Workplace 商业版Plus、企业版高级、专业版 Plus 以及教育对应项。
429请求过多。预配已超出 Zoom 的速率限制。请调查它是否在多个周期中持续存在。
#### 一种故障模式根本不会产生任何错误 Zoom 接受但并不对应任何内容的值——例如带有尾随空格的站点名称，或在 Zoom 中后来已重命名的角色名称——在语法上可能被接受，但实际上不会应用到任何内容。没有任何日志条目标记出这一情况。相同问题的基于平台的变体在第 6 步中有所说明。 {% hint style="info" %} **注意** 如果 Zoom 与身份提供商在用户的配置上不一致，请将身份提供商视为权威来源，并在那里更正该值。直接在 Zoom Web门户 中编辑会产生一种状态，而下一步预配事件 & 活动 &直播会将其覆盖，这会使根本问题更难诊断。 {% endhint %} ## **使用 Entra ID 配置 SCIM** #### Entra ID 的其他要求 * 具有访问企业版应用程序的 Entra ID 管理员权限 * 在 Entra ID 租户中已验证为自定义域的用户所使用的电子邮件域 #### Entra ID 的其他限制 * 属性映射仅来自 Entra *用户对象* 属性。安全群组不能直接为 Zoom 属性提供值；群组成员资格控制范围，而不是值。 * 增量预配周期大约每 40 分钟运行一次。启用预配后，变更不会立即生效。 * 该 `协作` 的值 `用户类型` 由于 Microsoft 的特定限制，Entra ID 不支持此功能。 {% hint style="info" %} **注意** 标准预配配置可从以下任一位置执行 `entra.microsoft.com` 或 `portal.azure.com`。不过，步骤 1 中使用的架构编辑器只能通过带有以下内容的 Azure Portal URL 访问 `forceSchemaEditorEnabled` 参数已附加。此标志对 `entra.microsoft.com`。请在本部分的所有步骤中使用第 1 步中的 Azure Portal 链接，以避免在配置过程中中途切换门户。 {% endhint %} ### 步骤 1：在 Zoom 应用程序架构中声明该属性 声明属性对每个属性来说都是一次性操作。请在配置任何映射之前声明您打算使用的每个属性，以便在步骤 2 中可用所有目标。 1. 使用架构编辑器 URL 登录 Azure 门户： `https://portal.azure.com/?Microsoft_AAD_Connect_Provisioning_forceSchemaEditorEnabled=true#home` 2. 在 **Azure 服务**，选择 **Microsoft Entra ID**. 3. 在左侧导航菜单中，在……下方 **管理**，单击 **企业版应用程序**. 4. 在应用程序列表中，单击你的 Zoom 应用程序。\ **注意**：应用程序名称由 Entra 管理员在创建应用程序时定义。它通常命名为 **Zoom** 或 **Zoom 单点登录**，但在你的租户中可能会有所不同。 5. 在左侧导航菜单中，在……下方 **管理**，单击 **配置**.\ **注意**：Azure 当前提供两种布局之一。在旧版体验中，选择 **编辑属性映射** 下方 **管理预配**。在较新的体验中，页面会在一个 **概述** 选项卡; 选择 **配置** 再次从左侧菜单进入。两条路线都会到达同一目的地。 6. 点击 **映射** 下拉菜单，然后单击 **配置 Microsoft Entra ID 用户**.\ **注意**: 在仍显示旧版命名的租户中，此选项显示为 **Provision Azure Active Directory Users**. 7. 在左下角，选择 **显示高级选项** 复选框。 8. 点击 **编辑 Zoom 的属性列表**. 9. 滚动到第一个空行，并完成以下内容： * **名称**：输入完整的属性字符串，例如 `urn:ietf:params:scim:schemas:extension:zoom:1.0:用户:zoomPhoneSite` * **类型**：选择 **字符串** 或 **布尔值**，与 SCIM2 API 参考中记录的数据类型匹配。 10. 对每个额外属性重复第 9 步。 11. 在左上角，点击 **保存**. {% hint style="warning" %} **注意** 属性名称区分大小写，必须与 API 参考完全一致。 `zoomPhoneSite` 是有效的； `zoomphonesite` 和 `ZoomPhoneSite` 不是。大小写错误的属性会被架构编辑器接受而不会报错，但在 Zoom API 中会静默失败。 对于文档中定义为 `布尔值`, **字符串** 的属性，只要映射的源提供字面文本 `true` 或 `false`，这也是有效的。选择 **字符串** 通常更实用，因为源是 Entra 扩展属性，它存储文本。 {% endhint %} ### 步骤 2：将目录源映射到该属性 Entra ID 提供三种映射类型，在它们之间的选择是配置中最关键的决定。
映射类型使用时机行为
直接Entra 字段已经包含 Zoom 期望的精确值。按原样传递源值。
常量范围内的每个用户都应接收相同的值。向每个已配置的用户发送固定值。
表达式该值必须通过用户属性派生、转换或变化。针对源字段计算表达式并发送结果。
**要创建映射：** 1. 返回到 **配置** → **映射** → **配置 Microsoft Entra ID 用户**. 2. 在左下角，点击 **添加新映射**. 3. 根据所选类型配置映射——请参阅下面的指导。 4. 点击 **目标属性** 下拉菜单并选择在步骤 1 中声明的属性。 5. 点击 **使用此属性匹配对象** 下拉菜单并选择 **否**.\ **注意**：自定义 Zoom 属性是配置值，不是身份匹配键。只有将 Entra 用户与 Zoom 用户相关联的属性——通常是 `用户名` — 应设置为 **是**. 6. 点击 **应用此映射** 下拉菜单并选择 **始终**，因此该值会在创建和后续更新时应用。 7. 点击 **确定**. 8. 对每个属性重复此操作，然后点击 **保存** 位于顶部的 **属性映射** 页面上配置映射。 #### 直接映射会原样传递现有字段，无需转换 * **映射类型**: **直接** * **源属性**：其值与 Zoom 所期望值逐字符完全匹配的 Entra 字段 * **如果为 null，则使用默认值（可选）**：当源字段为空时应用的回退值 直接映射是最不容易出错的选项，只要目录数据支持，就应优先使用。如果 `physicalDeliveryOfficeName` — 显示为 **办公位置** 在 Entra 用户配置文件中 — 已包含与 Zoom Phone 站点名称完全匹配的值，直接映射无需任何逻辑。 {% hint style="info" icon="lightbulb" %} **提示** 填充 **如果为 null，则使用默认值** 当缺失的源值会导致失败或意外结果时。默认值为 `主站点` 在站点映射中可确保没有办公位置的用户仍能成功预配，而不会处于未定义状态。 {% endhint %} #### 常量映射将一个值应用于范围内的整个群体 * **映射类型**: **常量** * **常量值**：要发送的固定值 常量映射适用于单一配置部署，也是多种 Zoom 特定行为背后的机制。将 `zoomPhoneExtNumber` 设置为常量 `0` 会指示 Zoom 在用户的站点内分配下一个可用分机，从而完全消除分机冲突。 #### 表达式映射会在预配时转换或派生值 * **映射类型**: **表达式** * **表达式**：嵌套的 `IIF()` 语句，用于评估一个或多个源属性 只要目录值和 Zoom 值不是同一字符串，就需要使用表达式映射： ``` IIF([officeLocation]="London","LON-01", IIF([officeLocation]="Manchester","MAN-01", "主站点")) ``` {% hint style="danger" %} **警告** 表达式会严格按照输入的文本进行比较，包括大小写。 `GB` 和 `gb` 是不同的值，以下也是如此： `英国` 和 `united kingdom`。比较失败不会引发错误 — 而是会落入默认分支，用户将在无提示的情况下以错误配置被预配。 {% endhint %} 将源值包装在 `ToUpper()` 中，并与大写字面量进行比较，以消除大小写不一致： ``` IIF(ToUpper([country])="GB","202", IIF(ToUpper([country])="UNITED KINGDOM","202", "-1")) ``` #### 源字段格式因创建 Entra 用户的方式而异 这是表达式映射最常见的原因：它们看起来正确，但在不同人群中表现不一致。 * **使用位置** 由 Microsoft 强制要求始终包含有效的 ISO 3166-1 alpha-2 代码，例如 `GB`，因为它决定许可证和功能/特性可用性。此字段是可靠的。 * **国家或地区** 没有此类强制要求，其内容取决于创建方法。通过 Entra 管理员门户 GUI 创建的用户会从完整国家名称的下拉菜单中选择，因此该字段通常存储 `英国`。通过 CSV 导入或 PowerShell 创建的用户通常会填充为 `GB` ——这是约定俗成，而非强制要求。 在任何通过多种方法创建了用户的租户中， `国家` 将不会保持一致的格式。在构建表达式之前，应先统一该字段，或者如上所示明确测试两种格式。 ### 步骤 3：将用户和群组纳入预配范围 分配决定配置会影响哪些用户。位于应用程序分配范围之外的用户不会受到任何映射的影响，这使得分配成为推出过程中的主要安全控制。 1. 转到 **Microsoft Entra ID** → **企业版应用程序** → 你的 Zoom 应用程序 → **用户和群组**. 2. 点击 **添加用户/群组**. 3. 在 **用户和群组**，选择目标用户或安全组。 4. 在 **选择角色**，选择适当的角色。 5. 点击 **分配**. 实际上只有两个角色值重要。其他选项，例如 **企业版** 和 **专业版** 要么是正在逐步淘汰的旧命名，要么是为不常见场景而设计的。
角色效果
基础版为用户开通，但不包含付费会议许可证。当由自定义属性——例如 Zoom Phone 通话套餐——负责分配付费权益时，请选择此项。
已授权分配 Zoom 账户的 默认 许可证计划，例如 Zoom Workplace 企业版 Plus。此屏幕不允许选择特定的捆绑包；默认设置在 Zoom 侧配置。
无论要预配多少个自定义属性，此角色选择都对添加到应用程序中的每个用户或群组仅应用一次。 **要将 Entra 群组预配为 Zoom 群组**，该功能默认处于禁用状态： 1. 转到 **配置** → **映射** 并选择 **预配 Microsoft Entra ID 群组**. 2. 切换 **已启用** 到 **是**. 3. 确认默认映射已就绪： `显示名称` → `显示名称`，和 `成员` → `成员`. 4. 点击 **保存**. 5. 返回到 **用户和群组** 并确认群组本身已分配给应用程序，而不仅仅是其各个成员。群组预配只会处理直接分配的群组。 {% hint style="warning" %} **注意：SCIM 对群组能做什么，不能做什么** 如果尚不存在同名的 Zoom 群组，SCIM 会使用 Entra 群组的 `显示名称` 按原样创建。该群组会带有成员，但 **不包含任何产品配置**。管理员仍需打开 **用户管理** → **群组管理** 在 Zoom Web门户中应用所需设置——群组级 Zoom Phone 策略、呼叫权限或其他产品配置。SCIM 预配的是群组的存在和成员资格；它并不定义该群组在 Zoom 中的作用。 {% endhint %} ### 第 4 步：使用按需预配进行验证 **按需预配** 独立于该项运行 **预配状态** 切换，这正是它是验证的正确工具的原因。直到此时为止的每一步——包括这一步——都可以在预配保持关闭时完成。 1. 转到 **配置** → **预配概览**. 2. 点击 **按需预配**. 3. 搜索并选择一个测试用户，然后单击 **预配**. 4. 查看结果。Entra 报告了它为每个预配事件 & 活动 &直播运行的四个阶段—— **导入**, **确定是否在范围内**, **匹配**，和 **预配** ——每个都可单独展开。 5. 确认所示属性值符合您的意图。 6. 登录 Zoom Web门户并确认配置已应用。 {% hint style="info" %} **推荐** 针对代表以下情况的用户进行验证： *最难的* 您的用户群中的情况——海外用户、通过不同方法创建的用户，或来源字段为空的用户。仅覆盖简单情况的测试不会暴露第 2 步所述的故障模式。 {% endhint %} ### 步骤 5：启用持续预配 启用预配会使配置立即对范围内的每位用户生效。请先完成并验证步骤 1 到 4。 1. 转到 **Microsoft Entra ID** → **企业版应用程序** → 你的 Zoom 应用程序 → **配置** → **配置**. 2. 切换 **预配状态** 到 **开**. 3. 点击 **保存**. 第一个周期最多大约需要 40 分钟。后续增量周期大约每 40 分钟运行一次。新加入者、属性更改和停用将按该安排/定时发送同步，而不是立即同步。 ### 第 6 步：使用 Entra 预配日志进行验证 1. 转到 **Microsoft Entra ID** → **企业版应用程序** → 你的 Zoom 应用程序 → **监控** → **预配日志**. 2. 搜索或筛选测试用户，然后选择相关的事件 & 活动 &直播。详细视图会打开，并显示四个选项卡： **步骤**, **故障排除与建议**, **已修改的属性**，和 **摘要**. 3. 查看 **摘要** 以确认该操作是成功还是失败。 4. 如果失败，请打开 **故障排除与建议**，其中显示了尝试执行的操作、受影响的用户主体名称，以及——在 **详情** — Zoom 的 API 返回的错误代码和完整错误消息。 这比检查映射 屏幕 更可靠，因为它显示的是传输的字面值，而不是映射原本希望产生的结果。当 Entra 日志无法得出结论时，请转到下述所描述的 Zoom App Marketplace 呼叫日志 **Zoom侧验证和常见错误**，显示原始请求和响应交互。 #### Entra ID 中的适职和离职行为 * 范围是主要的安全控制。位于应用程序分配范围之外的用户不会被此配置中的任何映射修改。 * 在 Entra 中停用用户，或将其移出范围，会自动反向执行预配并关闭离职流程的闭环。 * 每次失败都会生成相应的日志条目——如上所述，但需注意静默失败的 caveat。 ### 步骤 7：在 Entra ID 中应用参考场景 这些场景、先决条件和属性定义位于 [**参考场景**](#reference-scenarios) 部分。这里只提供 Entra 映射。 **场景 0——部门。** 在步骤 1 中，声明 `urn:ietf:params:scim:schemas:extension:企业版:2.0:用户:department` 为 **字符串**，注意使用企业版命名空间，而不是 Zoom One 的。将其映射为 **直接** 来自 Entra `部门` 字段。否 **如果为 null，则使用默认值** 无需——空的源字段只会发送空内容，而 Zoom 端无需存在任何对象。 **场景 1——Zoom Phone 站点和自动分机。** 映射 `zoomPhoneSite` 为 **直接** 来自 `physicalDeliveryOfficeName`，并带有 **如果为 null，则使用默认值** 设置为 `主站点`。映射 `zoomPhoneExtNumber` 为 **常量** 值为 `0` 除非您正在迁移现有的分机配置。若办公位置值与 Zoom 站点名称不完全匹配，请替换为一个 **表达式** 按步骤 2 所示格式的映射。 **场景 2——按国家/地区变化的通话套餐。** 由于 Entra 无法从群组获取值，因此需要使用表达式。请通过额外的 `IIF()` 按国家/地区分层，并同时处理 alpha-2 和全文格式，如步骤 2 所述： ``` IIF(ToUpper([country])="GB","202", IIF(ToUpper([country])="UNITED KINGDOM","202", IIF(ToUpper([country])="US","200", IIF(ToUpper([country])="UNITED STATES","200", "-1")))) ``` 当通话套餐属性分配付费权益时，请选择 **基础版** 而不是 **已授权** 在步骤 3 中。选择 **已授权** 还会同时应用账户的默认许可证，这可能不是预期的商业结果。 **场景 3——呼叫中心软件包、角色和地区。** 映射 `zoomContactCenterPackage` 带有一个 **表达式** 由区分坐席层级的目录字段驱动，并且 `zoomContactCenterRole` 为 **直接** 从包含角色名称的字段中获取。将 `zoomContactCenterRegion` 在单区域部署中保持未映射。 ## **使用 Okta 配置 SCIM** #### Okta 的附加要求 * 具有 Profile Editor 访问权限的 Okta 管理员权限 #### Okta 的附加限制 * 当用户属于多个为同一属性提供冲突值的群组时，只会传输优先级最高的群组的值。请参见步骤 5。 {% hint style="warning" %} **注意：两个配置文件，两个用途** Okta 维护着两个在此处很重要的不同配置文件，理解它们之间的区分可以避免大多数初始困惑。 **Okta 用户配置文件** 是值被 *存储* 在目录中的某个人员记录下。 **Zoom 用户应用程序配置文件** 是值被 *发送* 到 Zoom，其属性包含 SCIM 外部名称和命名空间。按用户配置需要这两者，并需要一个将它们连接起来的映射。按群组级别配置只需要应用程序配置文件属性，值设置在群组分配上。 {% endhint %} ### 步骤 1：在 Zoom 应用程序用户配置文件上声明该属性 这是实际向 Zoom 传输值的属性。声明它是每个属性一次性的操作。 1. 登录到 Okta 管理控制台。 2. 在左侧导航菜单中，点击 **应用程序**，然后点击 **应用程序**. 3. 在 **状态**，单击 **有效**. 4. 点击 **Zoom** 应用程序。\ **注意**：应用程序名称由 Okta 管理员在创建应用程序时定义。它通常命名为 **Zoom**，但在你的租户中可能会有所不同。 5. 点击 **配置** 选项卡。 6. 在 **Zoom 属性映射**，单击 **转到 Profile Editor**. 7. 在 **属性**，单击 **+ 添加属性**. 8. 完成以下内容： * **数据类型**：选择 **字符串** 或 **布尔值**，与 SCIM2 API 参考一致。 * **显示名称**：输入属性名称，例如 `zoomPhoneSite`. * **变量名称**：输入相同的名称。 * **外部名称**：输入 Zoom 文档中完全记录的属性名称，例如 `zoomPhoneSite`. * **外部命名空间**: 输入 `urn:ietf:params:scim:schemas:extension:zoom:1.0:用户:zoomPhoneSite` * **说明** (可选): 录制该属性为何存在以及其值来自哪里。 * **属性类型**：选择 **个人** 用于按用户的值，或 **群组** 用于通过群组成员关系继承的值。 9. 点击 **保存**，或 **保存并添加另一个**. {% hint style="danger" %} **警告** 外部名称和外部命名空间都必须正确。Zoom 的发布指南将外部命名空间指定为完整的 URN *包括* 属性名称——例如 `urn:ietf:params:scim:schemas:extension:zoom:1.0:用户:zoomRevenueAcceleratorRole` ——而不是仅使用命名空间。这与通用的 SCIM 约定不同。请遵循上面所示的格式，因为它反映了 Zoom 文档中有效的配置。 属性名称在整个过程中均区分大小写。大小写不正确的属性会被配置文件编辑器无错误地接受，但在 Zoom API 中会静默失败。 {% endhint %} ### 第 2 步：在 Okta 用户配置文件上创建源属性 如果该值按用户持有，请完成此步骤。如果每个用户的值都相同，或者它将改为在群组级别提供，则跳过此步骤。 1. 在左侧导航菜单中，点击 **目录**，然后点击 **个人资料编辑器**. 2. 点击 **用户** 选项卡。 3. 在…中 **用户** 框中，在…下方 **筛选器**，单击 **全部**. 4. 在…右侧 **Okta**，点击 **用户** 配置文件。 5. 在 **属性**，单击 **+ 添加属性**. 6. 完成以下内容： * **数据类型**：将 Zoom 属性与第 1 步中声明的属性匹配。 * **显示名称** 和 **变量名称**：输入一个名称，例如 `zoomPhoneSite`. * **枚举** （可选）：选择 **定义枚举值列表** 其中 Zoom 属性仅接受一组固定值。 * **属性必填** （可选）：选择 **是** 其中范围内的每个用户都必须具有一个值。 7. 点击 **保存**. {% hint style="info" icon="lightbulb" %} **提示** 为 Okta 用户配置文件属性和 Zoom 应用程序配置文件属性使用相同的名称。Okta 并不要求这样做，但匹配的名称会使映射列表具有自说明性，并且随着属性数量的增加，可大幅减少故障排除时间。 {% endhint %} 使用 **枚举** 可选选项，只要 Zoom 文档中说明了固定值集——呼叫中心套餐、Workplace 套件代码、Revenue Accelerator 计划值。将字段限制在输入时，可以防止拼写错误演变为静默的配置失败，并在数周后表现为缺少权限。 ### 步骤 3：将源属性映射到 Zoom 属性 1. 转到 **应用程序** → **应用程序** → **有效** → 该 **Zoom** 应用程序。 2. 点击 **配置** 选项卡。 3. 在 **Zoom 属性映射**，找到在第 1 步中声明的属性，并单击其右侧的编辑图标。\ **注意**：如果该属性不可见，请单击 **显示未映射的属性**. 4. 点击 **属性值** 下拉菜单并选择 **从 Okta 配置文件映射**. 5. 单击来源下拉菜单——它显示 `登录 | 字符串` 默认情况下——并选择在第 2 步中创建的 Okta 用户配置文件属性。 6. 选择 **创建并更新**.\ **注意**: **仅创建** 会在 Zoom 用户首次配置时应用该值，此后不再应用。对于在初始分配后不应被覆盖的值，请有意选择它；选择 **创建并更新** 在所有其他情况下都选择它，以便目录更改传播。 7. 点击 **保存**. 8. 对每个属性重复此操作。 {% hint style="warning" %} **提示：派生或翻译值** 当 Okta 值和 Zoom 值不是同一个字符串时， **属性值** 字段也接受 Okta 表达式语言，它支持条件逻辑和字符串函数。表达式语法和在线函数因 Okta 版本而异；请使用 **预览** 在更广泛应用之前，并查阅 Okta 当前的表达式语言文档以了解受支持的函数。 当转换很简单且值集较小时，直接在 Okta 属性上将 Zoom 值定义为枚举列表——或者像第 5 步中那样使用群组级属性——通常比表达式更易于维护。 {% endhint %} ### 第 4 步：启用向应用程序的配置 在相应的配置操作启用之前，属性映射不会生效。在第 5 步分配值之前请先启用它们。 1. 转到 **应用程序** → **应用程序** → **有效** → 该 **Zoom** 应用程序。 2. 点击 **配置** 选项卡。 3. 在 **向应用配置**，单击 **编辑**. 4. 启用下述设置，然后单击 **保存**. | 设置 | 效果 | | ---------- | ----------------------------------------------------------------- | | **创建用户** | 当应用程序分配给 Okta 中的用户时，会在 Zoom 中创建或链接用户。 | | **更新用户属性** | 当应用程序被分配时，会更新 Zoom 中用户的属性。后续对 Okta 用户配置文件的更改会自动覆盖 Zoom 中相应的值。 | | **停用用户** | 当应用程序在 Okta 中取消分配，或者 Okta 账户被停用时，会停用 Zoom 账户。重新分配该应用程序后，账户可以重新激活。 | {% hint style="danger" %} **警告** **更新用户属性** 这就是让自定义属性映射对现有用户生效的原因。没有它，映射只会在用户创建时应用，而 Okta 中随后发生的任何更改都不会传到 Zoom。 {% endhint %} ### 第 5 步：向用户或群组分配值 **要向单个用户分配一个值：** 1. 转到 **目录** → **人员** 并单击用户姓名。 2. 点击 **个人资料** 选项卡，然后单击 **编辑**. 3. 使用 Zoom 期望的值填充在第 2 步中创建的属性。 4. 点击 **保存**. 该值会立即传输。请在 Zoom Web门户 中确认结果，然后再更广泛地应用同样的更改。 **要向群组分配一个值** ——一种更具可扩展性的模式，其中配置遵循组织结构： 1. 确认该属性是在第 1 步中使用 **属性类型：群组**。如果它被声明为 **个人**，则通过重复第 1 步来声明一个群组级等效项，针对 **Zoom 用户** 配置文件 **目录** → **个人资料编辑器** → **用户** → **全部**下的 **群组** 将其选择为属性类型。 2. 转到 **目录** → **群组** → 该 **全部** 选项卡，然后单击 **添加群组**. 3. 输入一个 **名称** 和可选 **说明**，然后点击 **保存**. 4. 打开群组并点击 **应用程序** 选项卡。 5. 点击 **分配应用程序**，然后点击 **分配** 在……的右侧 **Zoom** 应用程序。 6. 使用应适用于每个成员的值填充群组级属性。 7. 点击 **保存并返回**，然后点击 **完成**. 8. 点击群组的 **人员** 选项卡，然后单击 **分配人员**. 9. 按名字、主电子邮件地址或用户名搜索用户，并点击每个条目旁边的添加按钮。 10. 点击 **完成**. 成员会自动继承群组的属性值。之后添加的用户在加入时也会继承这些值，这使得这种模式非常适合持续的适职，而不是一次性的迁移工作。 #### 当用户属于多个群组时，群组优先级会解决冲突的值。 当用户是多个为同一属性提供值的群组的成员时，Okta 会传递优先级最高的群组的值。 1. 转到 **应用程序** → **应用程序** → **有效** → 该 **Zoom** 应用程序。 2. 点击 **分配** 选项卡。 3. 在 **筛选器**，单击 **群组**. 4. 将群组拖放到预期顺序中。 {% hint style="info" %} **推荐** 将群组按从最具体到最通用的顺序排列，这样范围较窄的群组——特定站点或角色——就会优先于范围广泛的通用群组。反过来会让通用群组覆盖所有具体群组，这通常表现为整个用户群体收到相同的非预期配置。 {% endhint %} ### 第 6 步：使用 Okta 系统日志进行验证 1. 转到 **报告** → **系统日志**. 2. 按目标用户或 Zoom 应用程序进行筛选，并将时间范围缩小到配置尝试。 3. 打开相关事件 & 活动 &直播并查看详情，其中包括结果以及下游应用程序返回的任何错误。 未解决的配置失败也会显示在 Zoom 应用程序的 **配置** 选项卡。 如果 Okta 日志无法得出结论，请转到所述的 Zoom App Marketplace 呼叫日志，位于 **Zoom侧验证和常见错误**，显示原始请求和响应交互。 {% hint style="warning" %} **注意：Okta 特有的静默失败** 在 Zoom 用户资料中声明的属性，但从未映射，或映射时没有 **更新用户属性** 在第 4 步中启用后，它会在映射列表中仍保持可见，但不会传输任何内容。不会抛出错误。如果某个值没有到达 Zoom，而且系统日志中根本没有显示任何相应的事件 & 活动 &直播，请在进一步调查之前检查映射和配置设置。 {% endhint %} #### Okta 中的适职和离职行为 * 范围是主要的安全控制。在此配置中，未在 Okta 中分配 Zoom 应用程序的用户不会因任何映射而被修改。 * 与 **停用用户** 启用后，取消分配应用程序或停用 Okta 账户会自动停用 Zoom 账户。 * 重新分配应用程序会重新激活先前已停用的 Zoom 账户，这使群组成员资格成为管理离职和返岗用户的可行机制。 ### 第 7 步：在 Okta 中应用参考场景 这些场景、先决条件和属性定义位于 [**参考场景**](#reference-scenarios) 部分。此处仅给出 Okta 配置。 **场景 0——部门。** 在第 1 步，使用以下内容声明该属性 **显示名称** 和 **变量名称** `部门`, **外部名称** `部门`，和 **外部命名空间** `urn:ietf:params:scim:schemas:extension:企业版:2.0:用户`。使用 **属性类型：个人**。Okta 的基础用户资料已包含一个 `部门` 属性，因此可以跳过第 2 步——在第 3 步直接从中映射，并选择 **创建并更新**. {% hint style="warning" %} **注意：企业版扩展属性的命名空间格式** 步骤 1 的警告说明了 Zoom 将属性名附加到 External 命名空间的惯例。该指导已针对 Zoom 扩展下的属性进行了文档说明。 `部门` 属于标准 SCIM 企业版扩展，其中 Okta 的正常行为是将命名空间和外部名称保存在不同字段中，如上所示。如果值未传达到 Zoom，请尝试附加形式—— `urn:ietf:params:scim:schemas:extension:企业版:2.0:用户:department` ——并确认哪种形式在 Marketplace 通话记录中成功。 {% endhint %} **如果……，替代方案 `部门` 已映射。** 以下任一项的行为都完全相同，位于同一父级下，并且没有前提条件——请将两个中的属性名替换为 **外部名称** 以及命名空间中的属性名；如果 Okta 配置文件中尚未有匹配项，请在步骤 2 添加一个匹配的源属性： | 属性 | 备注 | | ---------------- | ---------------------------------------------------------------- | | `成本中心` | 商业版字段，因用户而异，因此错误值会显现出来 | | `组织` | 通常在所有用户之间都相同，这使错误更难发现 | | `employeeNumber` | 通常已作为身份字段映射——在声明之前请先检查 | | `代词` | 位于……下方 **Zoom** 扩展而不是企业版那个，因此它使用与本指南中其他所有场景相同的命名空间，并完全避免了上面的格式问题 | **场景 1——Zoom Phone 站点和自动分机。** 声明 `zoomPhoneSite` 与 **属性类型：群组** 并将其值设置在每个站点的 Okta 群组上，因此群组成员身份直接决定站点，无需翻译逻辑。声明 `zoomPhoneExtNumber` 作为一个个人属性，默认值为 `0` ，除非您正在迁移一个已存在的扩展配置。 **场景 2——按国家/地区变化的通话套餐。** 声明 `zoomPhoneCallingPlan` 与 **属性类型：群组** 并按通话套餐区域创建每个群组，在每个群组的 Zoom 应用程序分配中设置套餐值。用户通过成员身份继承正确的套餐，而存储在 Okta 中的值正是 Zoom 期望的值。这也使配置能够从 **分配** 选项卡中可见且可审计，并且它能够抵御底层目录数据填充方式中的不一致。携带 `-1` 提供了一种在不删除用户的情况下取消通话权限配置的简洁方式。 **场景 3——呼叫中心软件包、角色和地区。** 声明 `zoomContactCenterPackage` 作为一个枚举属性，受限于这三个允许的值，因此永远不会输入无效的软件包。声明 `zoomContactCenterRole` 作为群组级属性，因为角色通常遵循团队结构。离开 `zoomContactCenterRegion` 在单区域部署中保持未映射。 ## 故障排除 ### 错误 #### 用户不存在或不属于此账户 当目标用户的电子邮件地址因已存在的账户而无法预配时，就会发生此错误。建议 Zoom 管理员直接联系用户，并手动将该用户邀请到该账户。

预配错误示例。

#### 您无法添加付费用户 当 SCIM 尝试为用户进行预配，而该账户上的许可证不足时，就会发生此错误。要解决此错误，必须将该用户预配为基础版用户，或者必须提供一个许可证以供预配。

预配错误示例。

### 使用 SCIM 日志排查用户预配问题 Zoom 在以下位置提供最近 100 条 API 请求日志 [Zoom Marketplace](https://marketplace.zoom.us/)。Zoom 管理员可以使用这些日志确认通过预配 API 发送和接收了哪些信息。要访问这些日志，请以 Zoom 管理员身份登录 Zoom Marketplace 并单击 **管理**。在下一页上，选择 **呼叫日志** 下方 **个人应用管理**。然后，单击一条记录以展开 API 日志并查看内容。 下图显示了一个 SCIM 用户预配请求示例，其中用户身份和许可证属性已被突出显示以供参考。

SCIM 用户预配请求示例。

与响应映射类似，Zoom 只能应用在预配请求中由身份提供商提交的信息。使用这些日志确认用户身份和许可证属性正在由身份提供商提交。如果这些声明中缺少预期信息，请联系您的身份提供商获取支持。 --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://library.zoom.com/technical-library/zh/guan-li-yuan-zhuan-qu/account-and-endpoint-management/scim-guide.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.