> 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 单点登录文章](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 配置。
* 这 `userType` Zoom 将该属性列为计划弃用。

## **简介**

### **了解 SCIM 属性**

了解 Zoom SCIM 属性构造方式的管理员可以配置 Zoom 支持的任何属性。按照步骤说明操作的管理员只能配置该步骤说明所描述的属性。本节介绍属性构造。将属性映射到数据来源的内容稍后在身份提供商部分中介绍。

#### <mark style="color:蓝色;">每个属性都有一个命名空间、一个名称、一个数据类型和一个允许的值</mark>

让我们从一个完整可用的示例开始。这里是用于将用户分配到 Zoom Phone 站点的标识符：

```
urn:ietf:params:scim:schemas:extension:zoom:1.0:User:zoomPhoneSite
```

此属性涉及四个属性。其中两个可在上面的行中看到。另外两个来自 API 参考资料，稍后需要在身份提供商的其他位置填写。就目前而言，我们关注其中两个： **命名空间** 以及 **名称**.

<table><thead><tr><th width="155.290771484375">属性</th><th>从示例中提取</th><th>它的作用</th></tr></thead><tbody><tr><td><strong>命名空间</strong></td><td><code>urn:ietf:params:scim:schemas:extension:zoom:1.0:User</code></td><td>告诉 Zoom 该设置属于哪个架构，并作为几乎所有 Zoom 产品和许可属性的共享基础。传递给 Zoom 时作为标识符的前半部分。</td></tr><tr><td><strong>名称</strong></td><td><code>zoomPhoneSite</code></td><td>标识正在写入的特定 Zoom 设置——这里指用户的 Zoom Phone 站点。传递给 Zoom 时作为标识符的后半部分。区分大小写。</td></tr><tr><td><strong>数据类型</strong></td><td><code>string</code></td><td>告知身份提供商该属性所包含的值类型，以便正确存储和格式化。它不会作为标识符的一部分传递，而是单独声明为 <strong>类型</strong> （在 Entra ID 中），或 <strong>数据类型</strong> （在 Okta 中）。</td></tr><tr><td><strong>允许的值</strong></td><td><code>LON-01</code>，Zoom Phone 站点名称</td><td>实际应用于用户的设置。某些属性可使用自由文本，其他属性则只能使用固定选项集 — <code>Essentials</code>, <code>高级版</code>，或 <code>精英</code> 例如，适用于 Zoom 呼叫中心。在配置时传递给 Zoom，由映射提供，而不是由标识符提供。</td></tr></tbody></table>

{% hint style="danger" %}
**警告**

Zoom 发布的用户扩展命名空间不止一个。产品配置和许可属性使用 `urn:ietf:params:scim:schemas:extension:zoom:1.0:User`，这是本指南始终使用的命名空间。标准企业版字段，例如 `department`, `manager`，以及 `costCenter` 使用 `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User`。第三， `urn:us:zoom:scim:schemas:extension:1.0:ZoomUser`，携带在 API 响应中返回的登录类型信息，而不是在配置过程中设置的信息。使用错误命名空间构建的属性会被您的身份提供商接受，但会被 Zoom 静默忽略。
{% endhint %}

#### <mark style="color:蓝色;">在 SCIM2 API 参考中找到你需要的属性</mark>

该 [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 账户中尚未分配的号码。

#### <mark style="color:蓝色;">组装标识符：父级、冒号、子级</mark>

其中列出的所有内容 `urn:ietf:params:scim:schemas:extension:zoom:1.0:User` 对象是一个 **子级** 它的。对象本身就是 **父级**。构建标识符时，先命名父级，再添加冒号，最后添加子级：

```
父级       urn:ietf:params:scim:schemas:extension:Zoom:1.0:用户
冒号        :
子级        zoomPhoneSite

标识符   urn:ietf:params:scim:schemas:extension:zoom:1.0:用户:zoomPhoneSite
```

这就是整个构造。无需从 Zoom 请求查找表，也无需生成任何内容——标识符就是你已经拥有的两个东西，用冒号连接起来。

#### <mark style="color:蓝色;">父级保持不变；只有子级会改变</mark>

由于父级是固定的，配置第二个、第五个或第十五个属性都是相同的操作，只是附加了不同的子项：

```
基础（父级）              urn:ietf:params:scim:schemas:extension:zoom:1.0:User

Zoom Phone 站点            urn:ietf:params:scim:schemas:extension:zoom:1.0:用户:zoomPhone站点
Zoom Phone 号码          urn:ietf:params:scim:schemas:extension:zoom:1.0:User:zoomPhoneNumber
Zoom Phone 扩展       urn:ietf:params:scim:schemas:extension:zoom:1.0:用户:zoomPhoneExtNumber
Zoom Phone 通话套餐    urn:ietf:params:scim:schemas:extension:zoom:1.0:用户:zoomPhoneCallingPlan
```

同一个父级承载着其他所有 Zoom 产品。产品发生变化时，其构造本身并不会改变：

```
呼叫中心软件包     urn:ietf:params:scim:schemas:extension:zoom:1.0:用户:zoomContactCenterPackage
Revenue Accelerator 角色   urn:ietf:params:scim:schemas:extension:zoom:1.0:用户: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 部分中介绍——以及决定首先处理哪些属性，下一步将介绍。

#### <mark style="color:蓝色;">两种映射：基础版和高级版</mark>

并非每个属性都具有相同的风险，因此在配置任何内容之前，值得先对它们进行排序。

本指南沿用这些术语 **基础版** 和 **高级** 来自 [SSO 字段指南](https://library.zoom.com/admin-corner/account-and-endpoint-management/sso-field-guide)，该指南在 SAML 响应映射方面也采用了相同的界定方式。这些术语描述的是 **Zoom 收到该值后会如何处理**，而不是配置该属性有多困难。从实现机制上看，两者完全相同：都记录在同一个 **更新用户** 请求正文中，都采用相同的“父项:子项”结构构建，也都通过相同的步骤在 Entra ID 和 Okta 中声明和映射。

* **基础映射** 会将文本写入用户的个人资料。Zoom 会按原样存储该值，且绝不会将其与任何内容进行核对。
* **高级映射** 对账户提出一项声明。Zoom 会获取该值并查找匹配的对象，或查找已购套餐中的空闲席位——而这项查找可能会失败。

<table><thead><tr><th width="199.435791015625"></th><th>基础版映射</th><th>高级映射</th></tr></thead><tbody><tr><td><strong>该值是什么</strong></td><td>存储在用户的 profile 中的文本</td><td>指向 Zoom 中某个对象的指针，或对已购买席位的认领</td></tr><tr><td><strong>示例</strong></td><td><code>department</code>, <code>title</code>, <code>costCenter</code></td><td><code>zoomPhoneSite</code>, <code>zoomContactCenterRole</code>, <code>zoomWorkplace</code></td></tr><tr><td><strong>父级</strong></td><td>顶级，或企业版扩展</td><td>Zoom 扩展</td></tr><tr><td><strong>Zoom 中的前提条件</strong></td><td>无</td><td>对象必须存在，或席位必须空闲</td></tr><tr><td><strong>如果值错误</strong></td><td>个人资料上出现了错误文本</td><td>该属性会被拒绝，或被静默忽略</td></tr></tbody></table>

这种区别会影响两个实际决策。它决定了 **你必须先在 Zoom 中创建什么** ——基本映射无需创建任何内容，高级映射则可能需要创建很多内容——同时也决定了 **一个错误的代价**。部门信息错误只是个人资料上的外观问题。站点名称错误或许可证席位不可用，会导致用户无法使用正常工作的电话，或无法使用其受聘使用的产品；在实际部署中，还可能剥夺已经拥有该权益的用户的使用权。

这种后果上的差异，正是下面将二者分开处理的原因。

#### <mark style="color:蓝色;">基础版映射：个人资料信息</mark>

基础版映射会填充用户的 Zoom 个人资料中的描述性字段。Zoom 会按原样存储每个值，且绝不会将其与现有对象进行验证，因此在 Zoom 中事先无需构建任何内容；如果某个值有误，也不会破坏任何东西。

**核心身份字段通常已完成映射。** `userName`, `name.givenName`, `name.familyName`, `displayName`，以及 `emails` 位于请求正文的顶层，完全没有父级；Entra ID 和 Okta 集成都能开箱即用地映射这些字段。请验证它们，而不是重新构建。 `title`, `phoneNumbers`，以及 `locale` 也属于顶层字段，但可能需要添加。

**企业版字段使用第二个父级。** 构造方式不变——只有父级不同：

```
基础（父级）         urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

部门            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:组织
经理               urn:ietf:params:scim:schemas:extension:企业版:2.0:用户:manager
```

通过 SCIM 填充部门和成本中心不再需要 SAML 映射。

{% hint style="info" %}
**建议**

先映射一个基础属性—— `department` 是个不错的选择，下面将以它为例进行说明： **场景 0** 在参考场景中——并先针对单个测试用户端到端运行，再配置 Zoom 扩展中的任何内容。一个 `department` 在 Zoom 个人资料中正确显示某个值，证明了架构声明、映射、范围设置，以及你读取配置日志的能力。后续每个高级属性的区别只在于它指向的对象，而不在于配置方式。
{% endhint %}

#### <mark style="color:蓝色;">高级映射：产品配置和授权</mark>

高级映射分配用户可以执行的内容：一个 Zoom Phone 站点和通话套餐、一个呼叫中心角色和软件包、一个 Workplace 套件、一个 Revenue Accelerator 分段。这些属性位于本指南中一直使用的 Zoom 扩展父级下。

关键区别在于，这些值不会被存储，而是会被 **解析**。Zoom 会获取你发送的值，并查找匹配的对象或在线席位。基础映射会将文本写入个人资料，而高级映射则会针对账户配置和资源清单提出请求，该请求可能会失败。

这就是本指南专门用一整节来讲前提条件的原因。每个高级属性都依赖于某些内容先已在 Zoom Web门户中创建或购买，而且其失败方式远没有拼错的职位名称那么宽容。

#### <mark style="color:蓝色;">每个配置共有的三层</mark>

无论是哪个属性或哪个身份提供商，工作都相同，都是这三层。只有每个控件的位置不同。

<table><thead><tr><th width="114.4166259765625">层</th><th>用途</th><th>Microsoft Entra ID</th><th>Okta</th></tr></thead><tbody><tr><td><strong>1. 声明</strong></td><td>告诉身份提供商，该属性存在于 Zoom 应用程序中，从而使其可作为映射目标。</td><td>步骤 1</td><td>步骤 1</td></tr><tr><td><strong>2. 映射</strong></td><td>定义值的来源。</td><td>步骤 2</td><td>第 2–3 步</td></tr><tr><td><strong>3. 范围</strong></td><td>确定配置适用于哪些用户以及何时运行。</td><td>步骤 3–5</td><td>步骤 4–5</td></tr></tbody></table>

一旦理解了这种模式，添加第五个或第十五个属性只是同样三层结构的重复，而不是一个新项目。

#### <mark style="color:蓝色;">Entra 和 Okta 的区别在于值可以从何处来源</mark>

这是两条路径之间最具决定性的架构差异，它也解释了为什么相同的业务需求会在 Entra 和 Okta 中产生不同的配置。

* **Entra ID 只能从用户对象属性中获取值。** 值必须来自用户字段——现有的目录字段或专门打造的扩展属性。如果目录值与 Zoom 值不是同一字符串，就需要使用表达式进行转换。
* **Okta 可以从用户个人资料或群组分配中获取值。** 声明属性时，使用 **属性类型：群组** 允许在群组上设置一次该值，并由每个成员继承。如果配置遵循组织结构，这就完全无需转换逻辑。

两种方法都并非普遍更好，但会导致不同的配置。

### **Zoom 端预配置要求**

#### <mark style="color:蓝色;">在尝试高级映射之前，Zoom 端的对象必须先存在，SCIM 才能引用它们</mark>

SCIM 是一种分配机制，而不是创建机制——它会将用户关联到 Zoom 账户上已存在的配置，且 **不能** 代表用户创建该配置。

很大一部分高级映射属性都是 **引用**：您发送的值必须能够解析为 Zoom 中已存在的对象，例如站点、角色、模板、已购买的套餐、特定电话号码或分机号。它们都遵循同一条规则：

> 如果某个属性指定某个对象，则该对象必须已存在，拼写必须与发送的内容完全一致，并且——若它来自有限资源池——必须具有未使用的容量。

当引用的对象不存在时，SCIM 既不会创建它，也不会将请求排队。该属性要么直接失败，错误会在预配日志中返回；要么被静默丢弃——Zoom 接受载荷，不应用任何内容，并报告成功。

以下各节按产品列出前提条件，并提供用于构建各项条件的导航路径和支持文章。请先阅读账户级说明，然后阅读您计划预配的每种产品对应的部分。

#### <mark style="color:蓝色;">在预配任何产品之前，均适用账户级前提条件</mark>

本指南开头列出的账户要求——实名网址、SSO、SCIM 授权和已验证的关联域——是后续所有属性的前提条件。在 [**管理中心**](https://zoom.com/account) → [**安全与信任**](https://zoom.com/account/setting/security)中配置安全设置和 SSO，并在 [**管理中心**](https://zoom.com/account) → **账户** → [**账户信息**](https://zoom.com/account)中管理关联域；请参阅 [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).
* **席位必须属于所请求的确切套餐。** 如果该特定套餐没有空闲席位，即使账户中的其他套餐显示有剩余容量，发送许可证属性也会失败。

#### <mark style="color:蓝色;">Zoom Phone</mark>

Zoom Phone 包含最多的引用属性，因为电话用户由多个预先购买或预先构建的基础设施部分组成。

| 属性                                           | 必须已存在的内容                                             | 如何创建                                                                                                                                                                                                                                                                                                                                                                                                             |
| -------------------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Zoom Phone 许可证本身                             | 一个可用的 Zoom Phone 席位——在以下任何内容可以附加之前的先决授权。             | 请提前购买。请参阅 [购买和分配 Zoom Phone 许可证](https://support.zoom.com/hc/en/article?id=zm_kb\&sysparm_article=KB0077929).                                                                                                                                                                                                                                                                                                    |
| `zoomPhoneSite`                              | 站点，其名称必须与所发送的值完全一致。省略该属性会分配账户的主站点；启用多个站点后，该站点会默认存在。  | [管理中心](https://zoom.com/account) → 产品配置 → 电话系统 → [公司信息](https://zoom.com/pbx/page/telephone/settings#/settings) → **添加站点**，或使用 **导入** 进行批量创建。请参阅 [管理多个站点](https://support.zoom.com/hc/en/article?id=zm_kb\&sysparm_article=KB0069716).                                                                                                                                                                           |
| `zoomPhoneNumber`                            | 已购买或已转入账户且目前未分配的号码。已由其他用户、呼叫队列或自动接线员持有的号码不能重复使用。     | [管理中心](https://zoom.com/account) → 产品配置 → 号码 → [电话号码](https://zoom.com/cpw/page/phoneNumbers#/number-list)。在此购买或转入号码，并将目标号码留为空闲，以便 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://zoom.com/account) → 产品配置 → 电话系统 → [用户和会议室](https://zoom.com/pbx/page/telephone/phoneUsers#/users) → 选择包含该分机号的对象 → **个人资料** → **分机号码** → **编辑**。请参阅 [更改电话用户设置](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/)中，或通过 `type` 由 [列出通话套餐](https://developers.zoom.us/docs/api/references/phone-calling-plans/) API 返回，且包含可用席位数量。 |
| `zoomPhoneCallingPlanSubscription` （仅限多订阅账户） | 在账户针对同一套餐拥有多个订阅时，该套餐应从中使用的特定订阅。                      | 套餐和账单 → 订阅管理。                                                                                                                                                                                                                                                                                                                                                                                                    |

**分机号码池由不同对象类型共用，而不仅限于用户。** 呼叫队列、自动接线员、共享线路组和公共区域电话都会占用同一号码范围内的分机。这是“分机已在使用”错误最常见的原因，因为管理员只检查用户列表时，分机看起来可能是空闲的。

**号码转入完成之前，无法分配该号码。** 号码必须已显示在账户中且尚未分配；发起号码转入并不能满足这两个条件。

**站点是最常见的阻碍因素** 因为创建站点本身也有要求。系统会根据现实地址数据库验证站点地址，因为这些地址是紧急通话服务的基础，因此虚构的地址和邮政编码组合会导致验证错误。批量导入站点时，“自动接线员”列应填写 `Yes` ，而不是界面中显示的标签文本；“来电显示名称”主要适用于美国和加拿大，如果该字段导致验证失败，可以留空。

#### <mark style="color:蓝色;">Zoom 呼叫中心</mark>

呼叫中心预配由角色和模板驱动。各个属性必须解析为现有的呼叫中心对象，而模板包含没有专用 SCIM 属性的设置。

| 属性                              | 必须已存在的内容                                            | 如何创建                                                                                                                                                                                                                                                                         |
| ------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `zoomContactCenterPackage`      | 使用未分配席位购买的软件包—— `Essentials`, `Premium`或 `Elite` 。  | 提前购买；要购买额外的 Premium 软件包，可能需要先联系 Zoom 支持。请参阅 [更改 Zoom 呼叫中心用户设置](https://support.zoom.com/hc/en/article?id=zm_kb\&sysparm_article=KB0060874).                                                                                                                                  |
| `zoomContactCenterAddonsPlan`   | 附加组件套餐，已购买且具有容量。                                    | 请提前购买；账户套餐和账单信息。                                                                                                                                                                                                                                                             |
| `zoomContactCenterRole`         | 角色，可以是标准或自定义角色，名称必须完全一致。省略时会分配默认的 Agent 角色，该角色默认存在。 | [管理中心](https://zoom.com/account) → CX 管理 → 呼叫中心 → [角色](https://zoom.com/cci/index/admin#/admin-next/admin-roles) → **添加** → 配置权限 → **保存**。请参阅 [管理 Zoom 呼叫中心角色](https://support.zoom.com/hc/en/article?id=zm_kb\&sysparm_article=KB0061941).                                  |
| `zoomContactCenterRegion`       | 区域。省略时会分配账户的主区域，该区域必须已配置。                           | [管理中心](https://zoom.com/account) → CX 管理 → 呼叫中心 → [偏好设置](https://zoom.com/cci/index/admin#/admin-preferences) → 区域 → **添加区域** → 输入名称并选择 SIP 区域 → **添加**。请参阅 [管理 Zoom 呼叫中心区域](https://support.zoom.com/hc/en/article?id=zm_kb\&sysparm_article=KB0057668).                    |
| `zoomContactCenterUserTemplate` | 用户模板，名称必须完全一致。添加类型模板在创建用户时应用；更新类型模板在更新时应用。          | [管理员中心](https://zoom.com/account) → CX 管理 → 呼叫中心 → 用户 → [模板](https://zoom.com/cci/index/admin#/admin-agents#templates) → **添加模板** → 选择 **添加** → 配置角色、套餐、队列和技能 → **添加**。请参阅 [管理 Zoom 呼叫中心用户设置模板](https://support.zoom.com/hc/en/article?id=zm_kb\&sysparm_article=KB0077757). |

{% hint style="danger" %}
**警告**

必须先由 Zoom 支持启用呼叫中心区域功能，然后才能创建区域，并且每个用户恰好属于一个区域。由于这是一项支持请求而不是自助切换功能，如果计划进行多区域部署，请尽早提出请求。
{% endhint %}

**收件箱、队列和技能没有 SCIM 属性。** 要为它们预配，请先在 [管理员中心](https://zoom.com/account) → CX 管理 → 呼叫中心中预先创建这些项目，将它们关联到用户模板，然后通过 `zoomContactCenterUserTemplate`分配该模板。因此，它们会成为 *模板* 的前置条件，而非单个用户的前置条件；随着这些要求发生变化，模板也就成为唯一需要维护的对象。

<table><thead><tr><th width="123.2821044921875">对象</th><th>如何创建</th></tr></thead><tbody><tr><td>队列</td><td><a href="https://zoom.com/account">管理员中心</a> → CX 管理 → 呼叫中心 → <a href="https://zoom.com/cci/index/admin#/admin-queues">队列</a> → <strong>添加队列</strong> → 名称、频道、客服人员 → <strong>保存</strong>。请参阅 <a href="https://support.zoom.com/hc/en/article?id=zm_kb&#x26;sysparm_article=KB0061959">管理 Zoom 呼叫中心队列</a>.</td></tr><tr><td>技能</td><td><a href="https://zoom.com/account">管理员中心</a> → CX 管理 → 呼叫中心 → <a href="https://zoom.com/cci/index/admin#/admin-next/admin-skills">技能</a> → 选择类别 → <strong>添加技能</strong> → 名称 → <strong>添加</strong>。请参阅 <a href="https://support.zoom.com/hc/en/article?id=zm_kb&#x26;sysparm_article=KB0059519">管理技能和技能类别</a>.</td></tr><tr><td>收件箱</td><td><a href="https://zoom.com/account">管理员中心</a> → CX 管理 → 呼叫中心 → <a href="https://zoom.com/cci/index/admin#/admin-next/admin-inbox">收件箱</a> → <strong>添加收件箱</strong>。请参阅 <a href="https://support.zoom.com/hc/en/article?id=zm_kb&#x26;sysparm_article=KB0059471">管理 Zoom 呼叫中心收件箱</a>.</td></tr></tbody></table>

**如果同时提供模板和单独的属性，则以单独提供的属性值为准。** 同时发送模板和  `zoomContactCenterRole` 时，角色属性会覆盖模板中的角色设置，因此引用的角色和模板都必须存在。

#### <mark style="color:蓝色;">Zoom Revenue Accelerator</mark>

| 属性                                                                  | 必须已存在的内容                        | 如何创建                                                                                                                                                                                                                                                                     |
| ------------------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `zoomRevenueAcceleratorPlan` 和 `zoomRevenueAcceleratorSubscription` | 已购买且有可用席位的 ZRA 套餐或订阅。           | 请提前购买；账户套餐和账单信息。                                                                                                                                                                                                                                                         |
| `zoomRevenueAcceleratorRole`                                        | 标准或自定义角色，例如  `销售经理` — 名称必须完全一致。 | [管理员中心](https://zoom.com/account) → 用户 → [角色](https://zoom.com/role#/) → **Revenue Accelerator** 选项卡 → **+ 添加角色** → 名称和描述 → **添加** → 配置权限 → **保存更改**。请参阅 [使用 Zoom Revenue Accelerator 角色管理](https://support.zoom.com/hc/en/article?id=zm_kb\&sysparm_article=KB0059285). |
| `zoomRevenueAcceleratorSegment`                                     | 用户所属的细分组。                       | Revenue Accelerator 管理员设置。                                                                                                                                                                                                                                               |
| `zoomRevenueAcceleratorRegion`                                      | 地区 — 例如， `US`.                  | Revenue Accelerator 管理员设置。                                                                                                                                                                                                                                               |

#### <mark style="color:蓝色;">Zoom Workplace 许可证和账户角色</mark>

除上述三种产品外，标准用户录制还包含遵循相同规则的角色和许可证引用。

| 属性                                                                                                                  | 必须已存在的内容                           | 如何创建                                                                                                                                                                                       |
| ------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `roles[]` (`value` / `显示`)                                                                                          | 账户角色，名称必须完全一致。角色由 SCIM 引用，绝不会由其创建。 | [管理员中心](https://zoom.com/account) → 用户 → [角色](https://zoom.com/role#/) → **添加角色** → 名称和说明 → 配置权限。请参阅 [使用角色管理](https://support.zoom.com/hc/en/article?id=zm_kb\&sysparm_article=KB0064983). |
| `zoomWorkplace` 以及其他许可证或附加组件属性——白板、Scheduler、Clips Plus、翻译字幕、劳动力管理、质量管理、合规性管理、CX 洞察、AI 销售助手及其 `...Subscription` 对应项 | 相应的套餐或附加组件，已购买且有未使用的席位。            | 账单与套餐 → 套餐管理 → 编辑套餐 → 增加许可证数量。请参阅 [升级账户和附加组件](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://zoom.com/account) → 安全与信任 → [单点登录](https://zoom.com/account/sso/saml).                                                                                                     |

对于许可证或附加组件属性，没有可命名的对象，但前置条件在效果上是相同的：如果该特定池中没有可用席位，分配就会失败。

#### <mark style="color:蓝色;">无前置条件的属性</mark>

所有基础映射属性均符合条件，详见 **基础映射：个人资料信息** — Zoom 会原样存储这些值，且从不根据现有对象验证它们。Zoom 扩展中的两个属性也采用相同方式：

* **自动分配的值** — `zoomPhoneExtNumber` 以……形式发送 `0`，由 Zoom 自行分配分机号。
* **账户自定义属性** —— `{customAttribute}` 字段，用于存储您发送的任意字符串。

**具有默认值的引用** 属于中间情况：省略 `zoomPhoneSite`, `zoomContactCenterRole`，或 `zoomContactCenterRegion` 分别回退到主站点、默认的坐席角色和主区域。这些默认项本身必须存在，而默认情况下它们确实存在。

**群组是个例外，但只是部分例外。** 启用群组预配后，SCIM 会创建尚不存在的 Zoom 群组，并完全按照源群组中输入的名称创建。它不会为该群组应用任何产品配置——该群组创建后只有成员，没有其他内容。仍须在以下位置配置 Zoom Phone 策略、呼叫权限和其他群组级设置： [管理中心](https://zoom.com/account) → 用户 → [群组](https://zoom.com/account/group#/) 群组显示后。

{% hint style="info" %}
**建议**

将 Zoom 侧搭建视为一个前置阶段，并进行单独确认；在属性映射工作开始之前完成并验证。站点、号码、套餐、角色和模板通常由不同于身份提供方配置的另一个团队负责，而在预配测试中发现缺失对象的成本远高于事先确认其存在。
{% endhint %}

### **正在准备您的目录数据**

SCIM 传输源中包含的任何内容。它不会进行验证、规范化或更正。在映射任何属性之前，请确认关于预期源的三点：

* **范围内的每位用户都会填入该字段。** 字段未填时，不会发送任何内容，或会发送已配置的默认值。
* **其值的格式和大小写保持一致。** 两个身份提供商中的比较逻辑都是精确匹配。
* **其值与 Zoom 预期的值完全一致。** Zoom 不会对站点名称、角色名称或套餐值进行模糊匹配。

如果现有字段无法同时满足这三个条件，那么专门为此次集成刻意填充的专门打造属性，比重新利用一个其他系统也会写入的字段更可持续。

{% hint style="info" %}
**建议**

在修改身份提供方配置之前，先确定唯一可信来源。大多数失败的 SCIM 部署，本质上都是以配置问题形式表现出来的目录数据问题。
{% endhint %}

### **参考场景**

本指南中使用了四个场景。无论身份提供方如何，它们的商业版需求和 Zoom 端前提条件都相同，因此在此处统一定义。每个身份提供方特定部分的结尾都会展示如何在该平台上实现这四个场景。

#### <mark style="color:蓝色;">场景 0：部门，作为第一个基础版映射</mark>

用户的部门应显示在其 Zoom 个人资料上，数据来源于目录。这是之前建议的基础映射，作为第一个端到端测试，并将其包含在此处，以便在身份提供方的两个部分中都能完成该流程。

**Zoom 端的先决条件。** 无。Zoom 会按收到的原样存储该值，且绝不会将其与现有对象进行验证。

**属性。** 请注意，父级与以下三种情况不同 — `department` 位于企业版扩展中，而不是 Zoom 扩展中。

| 属性                                                             | 类型  | 说明                                                  |
| -------------------------------------------------------------- | --- | --------------------------------------------------- |
| `urn:ietf:params:scim:schemas:extension:企业版:2.0:用户:department` | 字符串 | 自由文本。两个身份提供商都已在用户配置文件中包含 `department` 字段，因此无需新增源属性。 |

**为什么从这里开始。** 如果 Zoom 个人资料中正确显示了部门值，就说明架构声明、映射和作用域均配置正确，而且你也具备读取预配日志的能力，同时不会让许可证或电话配置面临风险。以下所有高级场景的区别仅在于属性指向的对象不同。

**先检查它是否已映射。** Entra ID 和 Okta 的默认映射各不相同，而且随着两家供应商更新其 Zoom 集成，映射也会发生变化。请查看 **预配** → **映射** 在 Entra 中，或 **Zoom 属性映射** 使用 **显示未映射的属性** 已在 Okta 中启用。如果 `department` 已映射，请验证它，而不是将其声明为重复项；如果你想从头开始配置某个属性， `costCenter`, `组织`，以及 `employeeNumber` 位于同一父级下，且行为完全相同。

#### <mark style="color:蓝色;">场景 1：Zoom Phone 站点和自动分机号码分配</mark>

应根据用户的办公室将其放入正确的 Zoom Phone 站点，并在无需管理员干预的情况下获得分机号码。

**Zoom 端的前提条件** 站点必须已存在。请在以下位置创建： [**管理中心**](https://zoom.com/account) → **产品配置** → **电话系统** → [**公司信息**](https://zoom.com/pbx/page/telephone/settings#/settings) → **添加站点**，或通过批量方式 **导入**。站点地址会根据真实地址数据库进行验证，因为它们支持紧急通话服务，因此虚构的地址和邮政编码组合将无法通过验证。

**属性。** 两者都采用命名空间 `urn:ietf:params:scim:schemas:extension:zoom:1.0:User:` 后面跟着名称。

| 属性                   | 类型  | 说明                 |
| -------------------- | --- | ------------------ |
| `zoomPhoneSite`      | 字符串 | 必须与 Zoom 站点名称逐字符匹配 |
| `zoomPhoneExtNumber` | 字符串 | `0` 触发自动分配         |

**为什么是这个值 `0` 事项。** Zoom 是唯一知道哪些分机已在使用中的系统——包括分配给呼叫队列和自动接待员而非用户的分机。将分机分配工作交给 Zoom，可以彻底避免一类配置失败。在迁移期间，如果需要保留现有分机号码，则适合从目录中获取分机，但映射应切换为 `0` 迁移完成后，这样后续加入的成员就不必依赖持续维护目录数据。

{% hint style="info" %}
**注意**

Zoom Phone 账户上的默认站点通常确切命名为 `主站点`，显示在 [**管理中心**](https://zoom.com/account) → **产品配置** → **电话系统** → [**公司信息**](https://zoom.com/pbx/page/telephone/settings#/settings)。依赖该名称前，请先确认特定账户上的名称，因为它可以重命名。
{% endhint %}

#### <mark style="color:蓝色;">场景 2：Zoom Phone 按国家/地区变化的通话套餐</mark>

一家跨国组织已购买独立的 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，它会返回每个计划的 `name`，其 `类型` ——你映射的代码——及其 `subscribed` 和 `在线` 席位数量。因此，一次调用即可确认套餐存在、获取要发送的值，并验证是否有容量可供分配。

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` 列为移除所有呼叫套餐时使用的值。将其用于未匹配的用户，会产生确定且明确的结果——不分配套餐——而不是像完全不发送值那样含糊不清。它还提供了一种简便方式，可在不删除用户的情况下取消配置呼叫权益。

#### <mark style="color:蓝色;">场景 3：Zoom 呼叫中心 软件包、角色和区域</mark>

呼叫中心坐席应在适职时分配正确的 ZCC 软件包和角色，而不是事后手动配置。此场景展示了该方法与产品无关——流程本身不会改变，只是属性名称和允许的值不同。

| 属性                         | 类型  | 允许的值                             |
| -------------------------- | --- | -------------------------------- |
| `zoomContactCenterPackage` | 字符串 | `Essentials`, `Premium`, `Elite` |
| `zoomContactCenterRole`    | 字符串 | 任何 ZCC 角色名称。默认值为 `Agent` 如果省略。   |
| `zoomContactCenterRegion`  | 字符串 | 任何已配置的 ZCC 区域。如果省略，则默认为主区域。      |

**有意省略属性。** 离开 `zoomContactCenterRegion` 在单区域部署中不进行映射，因为 Zoom 记录的默认值已经正确。若某个属性的默认值正确，省略它比映射它更可取——每项映射都意味着一项维护义务。

**操作说明。** SCIM2 参考文档还介绍了 `zoomContactCenterUserTemplate`，它会应用预先构建的 ZCC 模板。添加类型的模板会在创建用户时应用，更新类型的模板会在更新时应用；如果同一请求中同时提供了模板和单个属性值，则以单个属性值为准。如果 ZCC 配置足够复杂，以至于通过大量单独的属性映射来维护变得难以管理，那么可以考虑使用模板。

### **Zoom 侧验证和常见错误**

每个身份提供商都有自己的日志，在各身份提供商的第 6 步中有说明。下方的 Zoom 侧日志对两者相同，并且是 Zoom 实际收到内容的最终录制。

#### <mark style="color:蓝色;">Zoom App Marketplace 呼叫日志显示完整的请求和响应交换</mark>

1. 以账户所有者身份登录 Zoom Web门户。
2. 导航到 [**Zoom App Marketplace**](https://marketplace.zoom.us/) → **管理** → **账户中的应用**.
3. 选择代表身份提供程序连接的应用程序。对于 Entra，这通常名为 **Azure 标识** 或类似内容。
4. 打开 **通话记录** 选项卡。
5. 使用 **按端点搜索**，或使用日期范围、方法和状态筛选条件，查找相关通话。
6. 选择该行以展开它。
7. 查看 `requestBody` 以准确了解发送的内容，并查看 `response` 以准确了解 Zoom 返回的内容，包括生成的 Zoom 用户 ID、 `httpStatus`以及最终的属性集。

Zoom 会保留最近 100 条 API 请求日志，因此请及时排查失败，而不要等到后续的配置活动将其覆盖。

#### <mark style="color:蓝色;">常见配置错误及其原因</mark>

<table><thead><tr><th width="99.69622802734375">代码</th><th>消息</th><th>原因及解决方法</th></tr></thead><tbody><tr><td>400</td><td>账户尚未启用单点登录。</td><td>SSO 是 SCIM 的先决条件。请先在 Zoom 账户上启用并配置 SSO。</td></tr><tr><td>400</td><td>用户处于非活动状态或已被锁定。</td><td>无法在当前状态下更新目标 Zoom 用户。请在 Zoom Web门户中解决账户状态问题。</td></tr><tr><td>403</td><td>由于权限不足，请求被拒绝：“用户：编辑”。</td><td>SCIM 连接所使用的凭据缺少所需的范围。请使用所有者或管理员账户重新授权该连接。</td></tr><tr><td>404</td><td>用户不存在。</td><td>身份提供程序未将该用户关联到现有的 Zoom 用户。请验证匹配属性和用户名格式。</td></tr><tr><td>409</td><td>电子邮件域与账户的关联域不匹配。</td><td>该用户的电子邮件域未与 Zoom 账户关联。请先关联并验证该域，然后再进行预配。</td></tr><tr><td>409</td><td>无法添加付费用户。</td><td>没有所请求类型的许可证可用。请释放该账户上的容量，或将用户配置为基础版。</td></tr><tr><td>409</td><td>无法使用 [bundle name] 创建更多用户。</td><td>特定捆绑包已没有剩余名额。适用于 Workplace 商业版Plus、企业版高级、专业版Plus，以及教育对应项。</td></tr><tr><td>429</td><td>请求过多。</td><td>配置已超出 Zoom 的速率限制。若在多个周期中持续存在，请进行调查。</td></tr></tbody></table>

#### <mark style="color:蓝色;">一种失败模式根本不会产生任何错误</mark>

Zoom 接受但并不对应任何内容的值——例如带尾随空格的站点名称，或在 Zoom 中后来已重命名的角色名称——可能在语法上被接受，却不会应用到任何对象。没有日志条目标记这一情况。第 6 步涵盖了同一问题的特定平台变体。

{% hint style="info" %}
**注意**

如果 Zoom 和身份提供商对用户的配置有分歧，请将身份提供商视为权威，并在那里更正该值。直接在 Zoom Web门户中编辑会生成一种状态，而下一次配置事件 & 活动 &直播会将其覆盖，这使得底层问题更难诊断。
{% endhint %}

## **使用 Entra ID 配置 SCIM**

#### <mark style="color:蓝色;">Entra ID 的其他要求</mark>

* 具有访问企业版应用程序的 Entra ID 管理员权限
* 您的用户使用的电子邮件域已在 Entra ID 租户中验证为自定义域

#### <mark style="color:蓝色;">Entra ID 中的其他限制</mark>

* 属性映射仅以 Entra *用户对象* 属性为来源。安全群组不能直接为 Zoom 属性提供值；群组成员身份用于控制范围，而非属性值。
* 增量预配周期大约每 40 分钟运行一次。启用预配后，变更不会立即生效。
* 由于 Microsoft 特有的限制，Entra ID 不支持 `Collaboration` 作为 `userType` 的值。

{% hint style="info" %}
**注意**

标准预配配置可通过 `entra.microsoft.com` 或 `portal.azure.com`完成。不过，步骤 1 中使用的架构编辑器只能通过 Azure 门户 URL 访问，并且需要附加 `forceSchemaEditorEnabled` 参数。此标志对 `entra.microsoft.com`没有影响。为避免在配置过程中切换门户，本部分所有步骤均使用步骤 1 中的 Azure 门户链接。
{% 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 SSO**，但在你的租户中可能有所不同。
5. 在左侧导航菜单的 **管理**下，单击 **预配**.\
   **注意**：Azure 目前提供两种布局之一。在旧版体验中，选择 **编辑属性映射** 下的 **管理预配**。在新版体验中，页面会默认打开 **概述** 选项卡；从左侧菜单中再次选择 **预配** 。这两种路径都会到达同一位置。
6. 点击 **映射** 下拉菜单，然后点击 **预配 Microsoft Entra ID 用户**.\
   **注意**：在仍显示旧版命名方式的租户中，此选项显示为 **配置 Azure Active Directory 用户**.
7. 在左下角，选择 **显示高级选项** 复选框。
8. 点击 **编辑 Zoom 的属性列表**.
9. 滚动到第一个空行并完成以下内容：
   * **名称**：输入完整的属性字符串，例如 `urn:ietf:params:scim:schemas:extension:zoom:1.0:User:zoomPhoneSite`
   * **类型**：选择 **字符串** 或 **布尔值**，与 SCIM2 API 参考中记载的数据类型相匹配。
10. 对每个附加属性重复第 9 步。
11. 在左上角，点击 **保存**.

{% hint style="warning" %}
**注意**

属性名称区分大小写，必须与 API 参考完全一致。 `zoomPhoneSite` 是有效的； `zoomphonesite` 和 `ZoomPhoneSite` 则无效。架构编辑器会接受大小写不正确的属性，且不报错，但 Zoom API 会静默处理失败。

对于文档中标注为 `boolean`, **字符串** 的属性，如果映射的源提供字面文本，也可以使用 `true` 或 `false`。当源是存储文本的 Entra 扩展属性时，选择 **字符串** 通常更实用。
{% endhint %}

### 第 2 步：将目录源映射到属性

Entra ID 提供三种映射类型，而它们之间的选择是配置中最关键的决定。

<table><thead><tr><th width="133.376708984375">映射类型</th><th>何时使用</th><th>行为</th></tr></thead><tbody><tr><td><strong>直接</strong></td><td>Entra 字段已包含 Zoom 期望的确切值。</td><td>原样传递源值。</td></tr><tr><td><strong>常量</strong></td><td>范围内的每个用户都应接收相同的值。</td><td>向每个已预配用户发送固定值。</td></tr><tr><td><strong>表达式</strong></td><td>该值必须根据用户属性派生、翻译或变化。</td><td>针对源字段计算表达式并发送结果。</td></tr></tbody></table>

**要创建映射：**

1. 返回至 **预配** → **映射** → **预配 Microsoft Entra ID 用户**.
2. 在左下角，点击 **添加新映射**.
3. 根据所选类型配置映射——请参见下面的指导。
4. 点击 **目标属性** 下拉菜单，并选择第 1 步中声明的属性。
5. 点击 **使用此属性匹配对象** 下拉菜单和选择 **否**.\
   **注意**：自定义 Zoom 属性是配置值，而非身份匹配键。只有用于关联 Entra 用户与 Zoom 用户的属性（通常是 `用户名` — 应设置为 **是**.
6. 点击 **应用此映射** 下拉菜单和选择框 **始终**，因此该值适用于创建时和后续更新时。
7. 点击 **确定**.
8. 对每个属性重复此操作，然后点击 **保存** 位于 **属性映射** 页面顶部。

#### <mark style="color:蓝色;">直接映射会在不转换的情况下传递现有字段</mark>

* **映射类型**: **直接**
* **源属性**: 一个 Entra 字段，其值与 Zoom 所需的值逐字符完全一致
* **为空时的默认值（可选）**: 当源字段为空时应用的后备值

直接映射最不容易出问题；只要目录数据支持，就应优先采用。如果 `physicalDeliveryOfficeName` — 显示为 **办公地点** 在 Entra 用户配置文件中——其中已包含与 Zoom Phone 站点名称完全匹配的值，因此直接进行映射完全不需要任何逻辑。

{% hint style="info" icon="lightbulb" %}
**提示**

填充 **如果为 null，则使用默认值** 每当缺少源值会导致失败或产生意外结果时。默认值为 `主站点` 在站点映射中，这可确保没有办公位置的用户仍能成功完成预配，而不是进入未定义状态。
{% endhint %}

#### <mark style="color:蓝色;">常量映射会将一个值应用于作用范围内的整个对象群体</mark>

* **映射类型**: **常量**
* **常量值**：要发送的固定值

常量映射适用于单一配置部署，也是多种 Zoom 特定行为背后的机制。将 `zoomPhoneExtNumber` 设为 `0` 常量会指示 Zoom 在用户所属的站点中分配下一个可用分机，从而彻底避免分机冲突。

#### <mark style="color:蓝色;">表达式映射会在配置时转换或推导一个值</mark>

* **映射类型**: **表达式**
* **表达式**：一个嵌套的 `IIF()` 语句，用于评估一个或多个源属性

当目录值与 Zoom 值不是同一个字符串时，就需要使用表达式映射：

```
IIF([officeLocation]="London","LON-01",
IIF([officeLocation]="Manchester","MAN-01",
"主站点"))
```

{% hint style="danger" %}
**警告**

表达式会严格按照输入的文本进行比较，包括大小写。 `GB` 和 `gb` 是不同的值， `United Kingdom` 和 `united kingdom`也一样。比较失败不会引发错误，而是会转到默认分支，导致用户在未收到任何提示的情况下被错误地配置。
{% endhint %}

将源值包装在 `ToUpper()` 中，并与大写字面值进行比较，以消除大小写不一致的问题：

```
IIF(ToUpper([country])="GB","202",
IIF(ToUpper([country])="UNITED KINGDOM","202",
"-1"))
```

#### <mark style="color:蓝色;">源字段格式会因 Entra 用户的创建方式而异</mark>

这是表达式映射最常见的原因之一：它们看起来正确，却在不同对象群体中表现不一致。

* **使用位置** 由 Microsoft 强制要求始终包含有效的 ISO 3166-1 alpha-2 代码，例如 `GB`，因为该字段决定许可证和功能/特性的可用性。此字段是可靠的。
* **国家或地区** 没有此类强制要求，其内容取决于创建方式。通过 Entra 管理员门户 GUI 创建的用户会从完整国家/地区名称下拉列表中选择，因此该字段通常存储 `United Kingdom`。通过 CSV 导入或 PowerShell 创建的用户通常会被填入 `GB` ——这是惯例，而非强制要求。

在通过多种方式创建过用户的任何租户中， `country` 的格式都不会一致。请先统一该字段的格式，再构建表达式；或者如上所示，明确测试两种格式。

### 步骤 3：将用户和群组纳入预配范围

分配决定配置会影响哪些用户。应用程序分配范围之外的用户不会受到任何映射的影响，因此在推出期间，分配是主要的安全控制。

1. 转到 **Microsoft Entra ID** → **企业版应用程序** → 您的 Zoom 应用程序 → **用户和群组**.
2. 点击 **添加用户/群组**.
3. 在 **用户和群组**下，选择相应的用户或安全群组。
4. 在 **选择角色**下，选择合适的角色。
5. 点击 **分配**.

实际上，只有两个角色值有意义。其他选项，例如 **企业** 和 **专业版** 要么是正在逐步淘汰的旧命名，要么用于不常见的场景。

<table><thead><tr><th width="157.5225830078125">角色</th><th>作用</th></tr></thead><tbody><tr><td><strong>基础版</strong></td><td>为用户进行预配，但不授予付费会议许可证。若某个自定义属性——例如 Zoom Phone 通话套餐——负责分配付费权益，则选择此项。</td></tr><tr><td><strong>已授权</strong></td><td>设置 Zoom 账户的 <em>默认</em> 许可证计划，例如 Zoom Workplace 企业版 Plus。此屏幕不允许选择特定套装；默认选项在 Zoom 端配置。</td></tr></tbody></table>

无论正在预配多少自定义属性，此角色选择都会对添加到应用程序的每个用户或群组仅应用一次。

**将 Entra 群组预配为 Zoom 群组**（默认处于禁用状态）：

1. 转到 **预配** → **映射** 并选择 **预配 Microsoft Entra ID 群组**.
2. 将 **已启用** 切换为 **是**.
3. 确认默认映射已就绪： `displayName` → `displayName`，以及 `members` → `members`.
4. 点击 **保存**.
5. 返回 **用户和群组** 并确认群组本身已分配给应用程序，而不只是其各个成员。群组预配只会处理直接分配的群组。

{% hint style="warning" %}
**注意：SCIM 对群组能做什么、不能做什么**

如果尚不存在名称匹配的 Zoom 群组，SCIM 会使用 Entra 群组的 `displayName` 按原样创建群组。群组创建时会包含成员，但 **不会配置任何产品**。管理员仍需在 Zoom Web门户中打开 [**管理中心**](https://zoom.com/account) → **用户** → [**→**](https://zoom.com/account/group#/) 群组，并应用所需的设置，例如群组级别的 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 端验证和常见错误**，其中显示原始请求和响应的交互过程。

#### <mark style="color:蓝色;">Entra ID 中的适职和离职行为</mark>

* 范围是主要的安全控制。位于应用程序分配范围之外的用户不会被此配置中的任何映射修改。
* 在 Entra 中停用用户，或将其从范围中移除，会自动撤销预配并关闭离职闭环。
* 每次失败都会生成相应的日志条目——但如上所述，存在静默失败的注意事项。

### 步骤 7：在 Entra ID 中应用参考场景

场景、前提条件和属性定义位于 [**参考场景**](#reference-scenarios) 部分。本节仅列出 Entra 映射。

**场景 0 — 部门。** 在步骤 1 中，声明 `urn:ietf:params:scim:schemas:extension:企业版:2.0:用户:department` 作为 **字符串**，请务必使用企业版命名空间，而不是 Zoom 命名空间。将其映射为 **直接** 取自 Entra 的 `department` 字段。无需 **为空时的默认值** ——源字段为空时不会发送任何内容，也不必在 Zoom 端创建对象。

**场景 1 — Zoom Phone 站点和自动分机。** 将 `zoomPhoneSite` 的映射方式设为 **直接** ，来源为 `physicalDeliveryOfficeName`，并将 **为空时的默认值** 设为 `Main 站点`。映射 `zoomPhoneExtNumber` 的映射方式设为 **常量** 其值为 `0` 除非您要迁移现有的分机配置。如果办公位置的值与 Zoom 站点名称不完全匹配，请替换为一个 **表达式** 映射，格式如步骤 2 所示。

**场景 2 — 因国家/地区而异的通话套餐。** 由于 Entra 无法从群组获取值，因此需要使用表达式。可通过添加更多 `IIF()` 每个国家的图层，并按照第 2 步中的说明，同时考虑 alpha-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**

#### <mark style="color:蓝色;">Okta 的其他要求</mark>

* 具有访问配置文件编辑器权限的 Okta 管理员权限

#### <mark style="color:蓝色;">Okta 的其他限制</mark>

* 当用户属于多个为同一属性提供冲突值的群组时，只会传输优先级最高的群组的值。请参见步骤 5。

{% hint style="warning" %}
**提示：两个配置文件，两个用途**

Okta 维护着两个与此相关的不同配置文件，了解它们之间的区别可以避免大多数初期困惑。 **Okta 用户配置文件** 是存储值的 *位置* ，该值对应目录中的某个人。 **Zoom 用户应用程序配置文件** 是存储值的 *发送* 到 Zoom，其属性包含 SCIM 外部名称和命名空间。用户级配置需要这两项，以及连接它们的映射。群组级配置只需要应用程序配置文件属性，并将值设置在群组分配中。
{% endhint %}

### 步骤 1：在 Zoom 应用程序用户配置文件上声明该属性

这就是实际将值传输到 Zoom 的属性。为每个属性声明它只需执行一次。

1. 登录到 Okta 管理控制台。
2. 在左侧导航菜单中，点击 **应用程序**，然后点击 **应用程序**.
3. 在 **状态**，点击 **有效**.
4. 点击 **Zoom** 应用程序。\
   **注意**：应用程序名称由 Okta 管理员在创建应用程序时定义。它通常命名为 **Zoom**，但在您的租户中可能有所不同。
5. 点击 **配置** 选项卡。
6. 在 **Zoom 属性映射**下，点击 **前往个人资料编辑器**.
7. 在 **属性**下，点击 **+ 添加属性**.
8. 完成以下内容：
   * **数据类型**：选择 **字符串** 或 **布尔值**，与 SCIM2 API 参考一致。
   * **显示名称**：输入属性名称，例如 `zoomPhoneSite`.
   * **变量名称**：输入相同的名称。
   * **外部名称**：输入 Zoom 文档中列出的属性名称，例如 `zoomPhoneSite`.
   * **外部命名空间**：输入 `urn:ietf:params:scim:schemas:extension:zoom:1.0:User:zoomPhoneSite`
   * **描述** （可选）：记录此属性存在的原因及其值的来源。
   * **属性类型**：选择 **个人** 表示每个用户各自的值，或 **群组** 表示通过群组成员身份继承的值。
9. 点击 **保存**，或 **保存并添加另一个**.

{% hint style="danger" %}
**警告**

External name 和 External namespace 必须都正确。Zoom 发布的指南规定，External namespace 应为完整的 URN *包括* 属性名称——例如 `urn:ietf:params:scim:schemas:extension:zoom:1.0:User:zoomRevenueAcceleratorRole` ——而不是仅使用命名空间。这与通用 SCIM 约定不同。请按照上面所示的格式操作，因为这反映了 Zoom 文档中说明可正常工作的配置。

属性名称始终区分大小写。大小写错误的属性会被 Profile Editor 无错误地接受，并在 Zoom API 中静默失败。
{% endhint %}

### 步骤 2：在 Okta 用户配置文件上创建源属性

在按用户保留该值的情况下完成此步骤。如果每个用户的值都相同，或者该值将改为在群组级别提供，则跳过此步骤。

1. 在左侧导航菜单中，点击 **目录**，然后点击 **个人资料编辑器**.
2. 点击 **用户** 选项卡。
3. 在 **用户** 框中，在 **筛选条件**，点击 **全部**.
4. 在 **Okta**，点击 **用户** 个人资料。
5. 在 **属性**下，点击 **+ 添加属性**.
6. 完成以下内容：
   * **数据类型**：与第 1 步中声明的 Zoom 属性匹配。
   * **显示名称** 和 **变量名称**：输入一个名称，例如 `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. 点击源下拉菜单（默认显示 `login | string` ），然后选择在步骤 2 中创建的 Okta 用户配置文件属性。
6. 选择 **创建和更新**.\
   **注意**: **仅创建** 仅在首次预配 Zoom 用户时应用该值，此后不再应用。对于初始分配后不应被覆盖的值，请有意选择此选项；在其他所有情况下，请选择 **创建和更新** ，以便同步目录更改。
7. 点击 **保存**.
8. 对每个属性重复此操作。

{% hint style="warning" %}
**注意：推导或翻译值**

如果 Okta 值和 Zoom 值不是相同的字符串， **属性值** 字段也接受 Okta 表达式语言，该语言支持条件逻辑和字符串函数。表达式语法和可用函数因 Okta 版本而异；在更大范围应用表达式之前，请使用 **预览** 针对单个测试用户验证表达式，并查阅 Okta 最新的表达式语言文档以了解支持的函数。

如果翻译很简单且值集较小，通常比使用表达式更易于维护的做法，是将 Zoom 值直接在 Okta 属性上定义为枚举列表——或者像第 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. 将步骤 2 中创建的属性填入 Zoom 期望的值。
4. 点击 **保存**.

该值会立即传输。请在 Zoom Web门户 中确认结果，然后再更广泛地应用同样的更改。

**为群组分配值** ——更具可扩展性的模式，让配置遵循组织结构：

1. 确认在步骤 1 中将属性声明为 **属性类型：群组**。如果声明为 **个人**，请在 **Zoom 用户** 资料下重复步骤 1，声明对应的群组级属性，路径为 **目录** → **资料编辑器** → **用户** → **全部**，并选择 **群组** 作为属性类型。
2. 前往 **目录** → **群组** → **全部** 选项卡，然后点击 **添加群组**.
3. 输入 **名称** 和可选的 **描述**，然后点击 **保存**.
4. 打开群组，然后点击 **应用程序** 选项卡。
5. 点击 **分配应用程序**，然后点击 **分配** ，位于 **Zoom** 应用程序右侧。
6. 使用应适用于每个成员的值填充群组级属性。
7. 点击 **保存并返回**，然后点击 **完成**.
8. 点击群组的 **成员** 选项卡，然后点击 **分配成员**.
9. 按名字、主电子邮件地址或用户名搜索用户，然后单击每个用户旁边的添加按钮。
10. 点击 **完成**.

成员会自动继承群组的属性值。后续添加的用户在加入时也会继承这些值，这使得此模式更适合持续的适职，而不是一次性的迁移工作。

#### <mark style="color:蓝色;">当用户属于多个群组时，群组优先级会解决冲突的值</mark>

如果用户是多个为同一属性提供值的群组的成员，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 %}

#### <mark style="color:蓝色;">适职和离职行为在 Okta 中</mark>

* 范围是主要的安全控制措施。未在 Okta 中分配 Zoom 应用程序的用户，绝不会被此配置中的任何映射修改。
* 使用 **停用用户** 启用后，取消分配应用程序或停用 Okta 账户会自动停用 Zoom 账户。
* 重新分配应用程序会重新激活先前已停用的 Zoom 账户，这使群组成员资格成为管理离职者和回归者的可行机制。

### 第 7 步：在 Okta 中应用参考场景

场景、先决条件和属性定义请参见 [**参考场景**](#reference-scenarios) 部分。此处仅提供 Okta 配置。

**场景 0 — 部门。** 在步骤 1 中，声明属性并设置 **显示名称** 和 **变量名称** `department`, **外部名称** `department`，以及 **外部命名空间** `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User`。使用 **属性类型：个人**。Okta 的基础用户配置文件已经包含一个 `department` 属性，因此可以跳过步骤 2——在步骤 3 中直接从该属性映射，选择 **创建和更新**.

{% hint style="warning" %}
**注意：企业扩展属性的命名空间格式**

步骤 1 中的 WARNING 说明了 Zoom 将属性名称追加到 External 命名空间的约定。该说明适用于 Zoom 扩展下的属性。 `department` 属于标准 SCIM 企业扩展，Okta 的常规行为是将命名空间和外部名称保存在不同字段中，如上所示。如果该值未传递到 Zoom，请尝试附加形式 — `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department` — 并在 Marketplace 通话记录中确认哪个表单提交成功。
{% endhint %}

**备选方案（如果 `department` 已映射。** 以下任意一种方式的行为都相同，位于同一父级之下，且没有前置条件——只需替换两者中的属性名称 **外部名称** 和命名空间。如果 Okta 配置文件中尚无对应的源属性，请在第 2 步中添加：

| 属性               | 说明                                                            |
| ---------------- | ------------------------------------------------------------- |
| `costCenter`     | 商业版字段，在用户之间会变化，因此错误值会显现                                       |
| `组织`             | 通常在所有用户之间都相同，因此更难发现错误                                         |
| `employeeNumber` | 通常已经作为身份字段映射——在声明前请先检查                                        |
| `pronouns`       | 位于 **Zoom** 扩展下，而不是企业扩展下，因此它使用与本指南中所有其他场景相同的命名空间，完全避免了上述格式问题。 |

**场景 1 — Zoom Phone 站点和自动分机号。** 声明 `zoomPhoneSite` ，并设置 **属性类型：群组** ，然后在每个站点的 Okta 群组中设置其值。这样，群组成员身份即可直接决定站点，无需转换逻辑。声明 `zoomPhoneExtNumber` 为个人属性，默认值设为 `0` ，除非您正在迁移现有的分机号配置。

**场景 2 — 按国家/地区区分的通话套餐。** 声明 `zoomPhoneCallingPlan` ，并设置 **属性类型：群组** ，然后为每个通话套餐区域创建一个群组，在每个群组的 Zoom 应用程序分配中设置套餐值。用户通过群组成员身份继承正确的套餐，Okta 中存储的值与 Zoom 所需的值完全一致。这也使配置可在 **分配** 选项卡中查看和审计，并且不受底层目录数据填充方式不一致的影响。包含 `-1` 的群组提供了一种便捷的方法，可在不删除用户的情况下取消其通话权限。

**场景 3 — 呼叫中心软件包、角色和区域。** 声明 `zoomContactCenterPackage` 为枚举属性，并将其限制为三个允许值，以避免输入无效的软件包。声明 `zoomContactCenterRole` 为群组级属性，因为角色通常取决于团队结构。在单区域部署中，离开映射配置时应将 `zoomContactCenterRegion` 保持为未映射状态。

## 故障排除

### 错误

#### <mark style="color:蓝色;">用户不存在或不属于此账户</mark>

当目标用户的电子邮件地址因账户已存在而无法进行预配时，就会发生此错误。建议 Zoom 管理员直接联系该用户，并手动邀请其加入账户。

<div data-with-frame="true"><figure><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXdXyiyMnR4S4EhYFqFUXgrePk-RwciKw8-jcxKxViZiIZ4I2kp0j1f_alWR7Hq9WuYhwz6ohh4LodWERfiXSr27LFN20r-r95xBJ6AjD7lF9k58yIJeYLpMmHR3BHYcPTMYkVwqZw?key=ug1dFE_WGWGnyMfD5tJnNw" alt="" width="563"><figcaption><p>预配错误示例。</p></figcaption></figure></div>

#### <mark style="color:蓝色;">无法添加付费用户</mark>

当 SCIM 尝试预配用户，但账户许可证不足时，就会发生此错误。要解决此错误，必须将该用户预配为基础版用户，或者为预配提供可用许可证。

<div data-with-frame="true"><figure><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXdXyiyMnR4S4EhYFqFUXgrePk-RwciKw8-jcxKxViZiIZ4I2kp0j1f_alWR7Hq9WuYhwz6ohh4LodWERfiXSr27LFN20r-r95xBJ6AjD7lF9k58yIJeYLpMmHR3BHYcPTMYkVwqZw?key=ug1dFE_WGWGnyMfD5tJnNw" alt="" width="563"><figcaption><p>预配错误示例。</p></figcaption></figure></div>

### 使用 SCIM 日志排查用户预配问题

Zoom 在 [Zoom Marketplace](https://marketplace.zoom.us/)中提供最近 100 条 API 请求日志。Zoom 管理员可以使用这些日志，确认通过预配 API 发送和接收的信息。要访问这些日志，请以 Zoom 管理员身份登录 Zoom Marketplace，然后点击 **管理**。在下一页中，选择 **呼叫日志** 下方的 **个人应用管理**。然后，点击某条记录以展开 API 日志并查看其内容。

下图展示了 SCIM 用户预配请求示例，并突出显示了用户的身份和许可证属性，供参考。

<div data-with-frame="true"><figure><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXcIxosFPBR8E4f1hj0vZQ7_nxnRd_isIqJYhKTQbocw4UfXlCBCkscqx8bGvY8JwuazgtRROPJm9PCZfZ4hJ5GQBqBzJA-PgS-mXkptGa0xq82SMXjl9Ip-faCDk3OQuLUXK0iobQ?key=ug1dFE_WGWGnyMfD5tJnNw" alt=""><figcaption><p>SCIM 用户预配请求示例。</p></figcaption></figure></div>

与响应映射一样，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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://library.zoom.com/technical-library/zh/guan-li-yuan-zhuan-qu/account-and-endpoint-management/scim-guide.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
