你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
Azure 通信服务是一种与标识无关的服务，它提供多种权益：
- 采用自带标识（BYOI）模型，允许重复使用标识管理系统中的现有标识，并使用 Azure 通信服务标识对其进行映射。
- 适用于任何现有标识系统，不依赖于特定的标识提供者。
- 将用户的数据（如姓名）保密，因为不需要在 Azure 通信服务中复制它。
- 使用 Microsoft Entra ID 进行标识和访问管理的组织现在可以直接使用 Entra ID 用户访问 Azure 通信服务资源。 这种对 Entra ID 身份验证的新支持无需开发或运行自己的身份管理或授权代理服务。 此功能目前处于公开预览阶段。
Azure 通信服务标识模型使用两个关键概念。
自带标识 (BYOI)：与标识管理系统集成
Azure 通信服务支持自带标识（BYOI）模型，该模型允许与现有标识管理系统集成。 可以在 Azure 通信服务中创建用户标识并将其映射到自己的用户标识系统。 此方法使你能够管理用户标识和访问令牌，而无需在 Azure 通信服务中复制用户数据。
以下部分将指导你了解自带标识 (BYOI) 模型的关键概念：
- 如何映射用户标识： 自带标识（BYOI）模型中的用户标识映射。
- 如何创建和管理访问令牌：访问令牌。
- 如何为标识管理实现客户端-服务器体系结构： 用于自带标识（BYOI）模型的客户端服务器体系结构。
自带标识（BYOI）模型中的用户标识映射
当通过 SDK 或 REST API 创建用户标识时，Azure 通信服务将创建唯一的用户标识符。 不能直接在 Azure 通信服务中使用外部标识符，例如电话号码、用户/设备/应用程序 ID 或用户名。 相反，你需要使用通信服务标识，并根据需要维护与你自己的用户 ID 系统之间的映射。
可以免费创建 Azure 通信服务用户标识。 当用户使用聊天或呼叫等通信服务时，将产生唯一的费用。 使用生成的通信服务标识的方式取决于应用场景。 例如，可以将标识映射为 1:1、1:N、N:1 或 N:N，并且可以将其用于人类用户或应用。 最终用户可以使用多个设备同时参与多个通信会话。
管理 Azure 通信服务用户标识和你自己的标识系统之间的映射是你作为开发人员的责任，并且不是内置的。 例如，可以在现有用户表中添加 CommunicationServicesId 列来存储关联的 Azure 通信服务标识。
自带标识 (BYOI) 模型的客户端服务器体系结构中提供了更详细的映射设计描述。
（预览版）使用 customId 简化身份映射
Important
此功能从标识 SDK 版本 1.4.0-beta1 和 REST API 版本 2025-03-02-preview开始可用。
Note
此功能目前处于预览状态。
以前，开发人员负责维护自己的用户标识系统和 Azure 通信服务标识之间的映射。 通过引入 customId 参数，现在可以在创建通信服务标识时直接关联自己的用户标识符，例如电子邮件地址或内部用户 ID。
创建用户时如果使用customId，通过相同的方法再次调用时，Azure 通信服务将返回相同的customId标识。 这样就无需自行存储和管理映射。
SDK 和 REST API 都支持此功能，对于希望在会话、设备或服务之间保持一致的标识，而不会造成额外的存储开销，此功能特别有用。
访问令牌
创建用户标识后，最终用户需要具有特定作用域的访问令牌才能使用聊天或呼叫参与通信。 例如，只有具有作用域令牌 chat 的用户才能参与聊天。 只有具有作用域令牌 voip 的用户才能参与 VoIP 呼叫。
用户可以同时具有多个令牌。 Azure 通信服务支持多个令牌范围，以考虑需要完全访问权限和有限访问权限的用户。 访问令牌具有以下属性。
| Property | Description |
|---|---|
| Subject | 令牌表示的用户标识。 |
| Expiration | 访问令牌的有效期至少为 1 小时，最多为 24 小时。 过期后，访问令牌无效，无法用于访问服务。 要创建具有自定义过期时间的令牌，请指定所需的有效期，以分钟为单位 (>=60, <1440)。 令牌默认有效期为 24 小时。 建议对单个会议使用短生存期令牌，并为需要应用程序较长时间的用户使用较长的生存期令牌。 |
| Scopes | 范围定义可以使用令牌访问哪些服务（Chat/VoIP）。 |
访问令牌是 JSON Web 令牌 (JWT)，具有完整性保护。 即，如果不使访问令牌无效，就无法更改其声明，因为令牌签名不再匹配。 如果通信基元与无效令牌一起使用，则拒绝访问。 即使令牌没有加密或混淆，你的应用程序也不应依赖令牌格式或其声明。 令牌格式可以更改，并且不是 API 官方合同的一部分。 Azure 通信服务支持以下访问令牌范围。
聊天令牌范围
身份模型支持三个不同的聊天标记范围。 下表描述了每个范围的权限。
chatchat.joinchat.join.limited
| 容量 / 令牌范围 | chat |
chat.join |
chat.join.limited |
|---|---|---|---|
| 创建聊天线程 | Y | N | N |
| 使用 ID 更新聊天记录 | Y | N | N |
| 使用 ID 删除聊天线程 | Y | N | N |
| 将参与者添加到聊天线程 | Y | Y | N |
| 删除聊天会话中的参与者 | Y | Y | N |
| 获取聊天线程 | Y | Y | Y |
| 获取具有 ID 的聊天线程 | Y | Y | Y |
| 获取 ReadReceipt | Y | Y | Y |
| 创建 ReadReceipt | Y | Y | Y |
| 使用 ID 为聊天线程创建消息 | Y | Y | Y |
| 获取具有消息 ID 的消息 | Y | Y | Y |
| 使用消息 ID 更新自己的消息 | Y | Y | Y |
| 使用消息 ID 删除自己的消息 | Y | Y | Y |
| 发送键入指示符 | Y | Y | Y |
| 获取线程 ID 的参与者 | Y | Y | Y |
VoIP 令牌范围
标识模型支持两个 VoIP 令牌范围。 下表描述了每个范围的权限。
voipvoip.join
| 容量 / 令牌范围 | voip |
voip.join |
|---|---|---|
| 开始 VoIP 呼叫 | Y | N |
| 当用户已受邀请到会议室时，在 Virtual Rooms 中启动 VoIP 呼叫 | Y | Y |
| 加入正在进行的 VoIP 呼叫 | Y | Y |
| 当用户已受邀请到 Virtual Rooms 时，在虚拟会议室中加入正在进行的 VoIP 呼叫 | Y | Y |
| 所有其他通话中操作，例如静音/取消静音、共享屏幕等 | Y | Y |
| Virtual Rooms 中的所有其他通话中操作，如静音/取消静音、屏幕共享等 | 由用户角色决定 | 由用户角色决定 |
可以将 voip.join 范围与 Rooms 配合使用来创建预定的通话。 在此方案中，只有受邀用户获得访问权限，并且禁止用户创建任何其他调用。
撤销或更新访问令牌
- Azure 通信服务标识库可用于在访问令牌过期之前撤销访问令牌。 令牌吊销不是立即生效的。 传播可能需要 15 分钟。
- 删除标识、资源或订阅会撤销所有访问令牌。
- 如果要移除用户访问特定功能的能力，请撤销用户的所有访问令牌。 然后签发具有更有限权限的新访问令牌。
- 轮换访问密钥会撤销使用先前的访问密钥创建的所有活动访问令牌。 因此，所有身份都无法访问 Azure 通信服务，并且需要新的访问令牌。
用于自带标识（BYOI）模型的客户端服务器体系结构
通过受信任的服务创建和管理用户访问令牌，而不是在客户端应用程序中创建令牌。 需要连接字符串或Microsoft Entra 凭据来创建用户访问令牌。 请记住保护凭据，将凭据传递给客户端可能会泄露机密。 如果不正确管理访问令牌，导致令牌被随意分发并被他人滥用，可能会对您的资源产生额外的费用。
如果将访问令牌缓存到后备存储，建议对令牌进行加密。 访问令牌允许访问敏感数据，如果不受保护，则可用于恶意活动。 任何拥有用户访问令牌的人都可以访问用户的聊天数据或模拟用户参与通话。
确保在令牌中只包含客户端应用所需的范围，以遵循最小权限的安全原则。
- 用户启动客户端应用程序。
- 客户端应用程序与标识管理服务联系。
- 标识管理服务对应用用户进行验证。 对于用户匿名的应用场景，可以跳过身份验证，但要注意在服务中添加其他保护措施，如请求限制和 CORS，以减轻令牌滥用。
- 为用户创建或查找通信服务标识。
- 稳定的标识应用场景：标识管理服务维护应用标识和通信服务标识之间的映射。 （应用程序标识包括用户和其他可寻址对象，如服务或 bot。）如果应用标识是新的，则创建新的通信标识并存储映射。
- 临时标识应用场景：标识管理服务创建新的通信标识。 在此应用场景，同一用户在每个会话中都会使用不同的通信标识。
- 标识管理服务为适用的标识颁发用户访问令牌，并将其返回给客户端应用。
Azure 应用服务或 Azure Functions 是运行标识管理服务的两种替代方法。 这些服务可以轻松缩放，并具有内置功能来对用户进行身份验证。 它们与 OpenID 和第三方标识提供者（如 Facebook）集成。
Microsoft Entra ID：与 Entra ID 集成
Important
Azure 通信服务的这一功能目前以预览版提供。 预览版中的功能已公开发布，可供所有新客户和现有Microsoft客户使用。
预览版 API 和 SDK 在没有服务级别协议的情况下提供。 建议不要将它们用于生产工作负荷。 某些功能可能不受支持，或者功能可能受到限制。
有关详细信息，请参阅 Microsoft Azure 预览版补充使用条款。
Azure 通信服务现在支持Microsoft Entra ID 身份验证，允许你直接使用 Entra ID 用户访问 Azure 通信服务资源。 此对 Entra ID 身份验证的新支持消除了开发或运营 客户-服务器体系结构 中提到的自己身份管理或授权代理服务的需求。
以下部分将指导你完成 Microsoft Entra ID 集成的基本方面：
- 如何获取和管理访问令牌： 具有 Microsoft Entra ID 的访问令牌。
- 如何使用 Microsoft Entra ID 实现客户端体系结构： Microsoft Entra ID 的客户端体系结构。
- 当前限制和建议指南： 限制。
具有 Microsoft Entra ID 的访问令牌
Azure 通信服务中的身份验证和授权仅支持 Azure 通信服务访问令牌，包括聊天和呼叫功能。 有关令牌结构和管理的详细信息，请参阅 Access 令牌。 在Microsoft Entra ID 公共预览版期间，通过 Entra ID 集成仅支持调用 （VoIP） 访问令牌范围。
通过Microsoft Entra ID 集成，通过 Entra ID 对用户进行身份验证，获取具有 Azure 通信服务客户端应用程序的 API 权限的 Entra ID 用户访问令牌，并将其交换为 Azure 通信服务访问令牌。 Azure 通信服务通用 SDK 通过自动获取 Entra ID 用户的 Azure 通信服务访问令牌来提供无缝身份验证。 有关如何使用 Azure 通信服务通用 SDK 实现逻辑的详细信息，请参阅 获取Microsoft Entra ID 用户的访问令牌
Azure 通信服务客户端应用程序的 API 权限与 聊天令牌范围 和 VoIP 令牌范围中所述的 Azure 通信服务访问令牌范围一致命名。 下表显示了 API 权限与访问令牌范围之间的映射。
Important
公共预览版中的 Microsoft Entra ID 尚不支持聊天（消息）API 权限（Chat，Chat.JoinChat.Join.Limited）。 目前，只有与 VoIP 相关的权限（VoIP， VoIP.Join）可用。 将在未来更新中提供聊天支持。
| Azure 通信服务客户端 API 权限 | Azure 通信服务访问令牌范围 |
|---|---|
Chat （Entra ID 公开预览版：仅限 VoIP — 聊天功能即将推出） |
chat |
Chat.Join（Entra ID 公共预览版：仅限 VoIP，聊天功能即将推出） |
chat.join |
Chat.Join.Limited （Entra ID 公共预览：仅限 VoIP - 聊天功能即将推出） |
chat.join.limited |
VoIP |
voip |
VoIP.Join |
voip.join |
Azure 通信服务访问令牌的过期时间与 Microsoft Entra ID 用户访问令牌相同。
Microsoft Entra ID 的客户端体系结构
通过Microsoft Entra ID 集成，可以直接使用 Entra ID 进行身份验证和授权来简化体系结构。 以下步骤概述了该过程：
- 用户启动客户端应用程序。
- 客户端应用程序通过 Microsoft Entra ID 对用户进行身份验证。 客户端应用程序获取具有 Azure 通信服务客户端应用程序的 API 权限的 Entra ID 用户访问令牌。
- 客户端应用程序使用以下方法之一为 Entra ID 用户获取 Azure 通信服务访问令牌：
- 使用 Azure 通信服务通用 SDK：客户端使用 Entra ID 令牌凭据选项初始化 CommunicationTokenCredential ，该选项会自动处理在后台获取 Entra ID 用户的 Azure 通信服务访问令牌。 然后，应用程序使用此凭据访问 Azure 通信服务 API。
- 自定义实现：客户端应用程序调用 Azure 通信服务访问令牌 API 的 Exchange Entra ID 令牌 以获取 Azure 通信服务访问令牌。 然后，生成的 Azure 通信服务访问令牌用于访问 Azure 通信服务 API。
此体系结构无需单独的标识管理服务，因为 Microsoft Entra ID 直接处理用户身份验证和授权。
局限性
Microsoft Entra ID 集成目前处于预览状态，并具有以下限制：
- 连续访问评估 不可用。 若要立即撤销访问令牌，请按照 撤销访问令牌中的说明作。
- 删除 Entra ID 用户不会自动从通信服务资源中删除所有关联数据。 若要确保删除所有数据，请按照删除身份中的说明操作。
- 无法在公共预览版中通过 Microsoft Entra ID 集成授予或使用聊天（消息）API 权限（
Chat，Chat.JoinChat.Join.Limited）。 仅支持与 VoIP 相关的权限（VoIP，VoIP.Join）。 使用 BYOI 身份模型来获取聊天访问令牌，直到正式发布（GA）。
后续步骤
- 若要颁发令牌，请参阅 为最终用户创建和管理访问令牌。
- 有关身份验证的简介，请参阅对 Azure 通信服务进行身份验证。
- 有关身份验证在单租户和多租户Microsoft Entra ID 方案中的工作原理的详细信息，请参阅 Microsoft Entra ID 中的租户。
- 有关如何对 Microsoft Entra ID 用户进行身份验证的快速入门，请参阅 Microsoft Entra ID 用户进行身份验证。
- 要了解数据驻留和隐私，请参阅区域可用性和数据驻留。
- 有关简单标识管理服务的完整示例，请参阅 “受信任的服务”教程。
- 有关与 Entra ID 和 Microsoft Graph 集成的更高级标识管理示例，请参阅 身份验证服务 hero 示例。