通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

如何为客户端生成客户端访问 URL

  • 项目

客户端（无论是浏览器 💻、移动应用 📱 还是 IoT 设备 💡）使用客户端访问 URL 来连接资源并对其进行身份验证。

URL 遵循以下模式：

  • 对于 MQTT 客户端，是 wss://<service_name>.webpubsub.azure.com/clients/mqtt/hubs/<hub_name>?access_token=<token>。
  • 对于所有其他客户端，是 wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>。

本文介绍获取客户端访问 URL 的几种方法。

从 Azure 门户复制

在 Azure 门户 的“密钥”选项卡中，有一个“客户端 URL 生成器”工具，可用于为你快速生成客户端访问 URL，如下图所示。 不存储此处输入的值。

注意，对于 MQTT 客户端，应该在“客户端访问 URL”文本框前面的下拉菜单中选择“MQTT 客户端”。

Azure Web PubSub 客户端 URL 生成器的屏幕截图。

从服务 SDK 生成

可以使用 Web PubSub 服务器 SDK 生成相同的客户端访问 URL。

  1. 按照服务器 SDK 入门创建 WebPubSubServiceClient 对象 service

  2. 通过调用 WebPubSubServiceClient.getClientAccessToken 来生成客户端访问 URL：

    • 生成客户端访问令牌

      // for web pubsub native clients
let token = await serviceClient.getClientAccessToken();

// for mqtt clients
let token = await serviceClient.getClientAccessToken({ clientProtocol: "mqtt" });

    • 配置用户 ID

      let token = await serviceClient.getClientAccessToken({ userId: "user1" });

    • 配置令牌的生存期

      let token = await serviceClient.getClientAccessToken({
  expirationTimeInMinutes: 5,
});

    • 配置一个角色，以便在使用此客户端访问 URL 进行连接时可以直接加入组 group1

      let token = await serviceClient.getClientAccessToken({
  roles: ["webpubsub.joinLeaveGroup.group1"],
});

    • 配置一个角色，以便在使用此客户端访问 URL 进行连接时，客户端可以直接将消息发送到组 group1

      let token = await serviceClient.getClientAccessToken({
  roles: ["webpubsub.sendToGroup.group1"],
});

    • 配置组 group1，以便在使用此客户端访问 URL 进行连接后，客户端可以加入它

      let token = await serviceClient.getClientAccessToken({
  groups: ["group1"],
});

在实际代码中，我们通常有一个服务器端来托管生成客户端访问 URL 的逻辑。 当客户端请求传入时，服务器端可以使用常规身份验证/授权工作流来验证客户端请求。 只有有效的客户端请求才能取回客户端访问 URL。

从 REST API :generateToken 生成

还可以使用 Microsoft Entra ID，通过调用生成客户端令牌 REST API 来生成令牌。

注意

Web PubSub 不建议手动为 Microsoft Entra ID 服务主体创建 Microsoft Entra ID 令牌。 这是因为每个 Microsoft Entra ID 令牌的生存期很短，通常在一小时内就会过期。 在此时间之后，必须手动生成替换 Microsoft Entra ID 令牌。 请改用我们的 SDK 来自动生成 Microsoft Entra ID 令牌和替换已过期的令牌。

  1. 按照从应用程序授权中的要求启用 Microsoft Entra ID。

  2. 获取 Microsoft Entra 令牌。

  3. 使用 Microsoft Entra 令牌调用 :generateToken。

  4. 收集以下信息：

    值名称 如何获取值
    TenantId TenantId 是注册的应用程序的“概述”窗格中的“目录(租户) ID”值。
    ClientId ClientId 是注册的应用程序的“概述”窗格中的“应用程序(客户端) ID”值。
    ClientSecret ClientSecret 是在步骤 1 中添加的客户端机密的值

  5. 从 Microsoft 标识平台获取 Microsoft Entra ID 令牌

    我们将使用 CURL 工具来演示如何调用 REST API。 该工具已捆绑在 Windows 10/11 中，你可以按照安装 CURL 所述安装该工具。

    # set necessary values, replace the placeholders with your actual values
export TenantId=<your_tenant_id>
export ClientId=<your_client_id>
export ClientSecret=<your_client_secret>

curl -X POST "https://login.microsoftonline.com/$TenantId/oauth2/v2.0/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=client_credentials" \
--data-urlencode "client_id=$ClientId" \
--data-urlencode "client_secret=$ClientSecret" \
--data-urlencode "scope=https://webpubsub.azure.com/.default"

    上述 curl 命令向 Microsoft 标识终结点发送 POST 请求以获取 Microsoft Entra ID 令牌。 响应中的 access_token 字段显示了 Microsoft Entra ID 令牌。 复制并存储该 URL，以供稍后使用。

  6. 使用 Microsoft Entra ID 令牌调用 :generateToken

    # Replace the values in {} with your actual values.
export Hostname={your_service_hostname}
export Hub={your_hub}
export Microsoft_Entra_Token={Microsoft_entra_id_token_from_previous_step}
curl -X POST "https://$Hostname/api/hubs/$Hub/:generateToken?api-version=2024-01-01" \
-H "Authorization: Bearer $Microsoft_Entra_Token" \
-H "Content-Type: application/json"

    如果需要为 MQTT 客户端生成令牌，请将 clientType=mqtt 参数追加到 URL 中：

    export Hostname={your_service_hostname}
export Hub={your_hub}
export Microsoft_Entra_Token={Microsoft_entra_id_token_from_previous_step}
curl -X POST "https://$Hostname/api/hubs/$Hub/:generateToken?api-version=2024-01-01&clientType=mqtt" \
-H "Authorization: Bearer $Microsoft_Entra_Token" \
-H "Content-Type: application/json"

    运行 cURL 命令后，应该收到如下所示的响应：

    {
  "token": "ABCDEFG.ABC.ABC"
}