Как создать URL-адрес доступа клиента для клиентов

Клиент, будь то браузер 💻, мобильное приложение 📱или устройство 💡Интернета вещей, использует 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
• Для разработки создайте значение с помощью пакета SDK для сервера Web PubSub
• Если вы используете идентификатор Microsoft Entra, вы также можете вызвать REST API создания маркера клиента.

Копирование из портал Azure

На вкладке "Ключи" в портал Azure есть средство генератора URL-адресов клиента, чтобы быстро создать URL-адрес клиентского доступа, как показано на следующей схеме. Входные значения здесь не хранятся.

Обратите внимание, что для клиентов MQTT следует выбрать "Клиент MQTT" в раскрывающемся меню перед текстовым полем "URL-адрес клиентского доступа".

Создание из пакета SDK службы

Тот же URL-адрес клиентского доступа можно создать с помощью пакета SDK для сервера Web PubSub.

JavaScript

1. Следуйте инструкциям по началу работы с пакетом WebPubSubServiceClient SDK для сервера, чтобы создать объектservice

2. Создайте URL-адрес клиентского доступа путем вызова WebPubSubServiceClient.getClientAccessToken:

   • Создание маркера доступа клиента

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

   • Настройка идентификатора пользователя

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

   • Настройка времени существования маркера

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

   • Настройка роли, которая может присоединиться group1 непосредственно при подключении с помощью этого URL-адреса клиентского доступа

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

   • Настройка роли, которую клиент может отправлять сообщения в группу group1 непосредственно при подключении с помощью этого URL-адреса клиентского доступа

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

   • Настройка группы group1 , присоединенной клиентом после подключения с помощью этого URL-адреса клиентского доступа

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

C#

1. Следуйте инструкциям по началу работы с пакетом WebPubSubServiceClient SDK для сервера, чтобы создать объектservice

2. Создайте URL-адрес клиентского доступа путем вызова WebPubSubServiceClient.GetClientAccessUri:

   • Создание маркера доступа клиента

     // for web pubsub native clients
     var url = service.GetClientAccessUri();
     
     // for mqtt clients
     var url = service.GetClientAccessUri(clientProtocol: WebPubSubClientProtocol.Mqtt);
     

   • Настройка идентификатора пользователя

     var url = service.GetClientAccessUri(userId: "user1");
     

   • Настройка времени существования маркера

     var url = service.GetClientAccessUri(expiresAfter: TimeSpan.FromMinutes(5));
     

   • Настройка роли, которая может присоединиться group1 непосредственно при подключении с помощью этого URL-адреса клиентского доступа

     var url = service.GetClientAccessUri(roles: new string[] { "webpubsub.joinLeaveGroup.group1" });
     

   • Настройка роли, которую клиент может отправлять сообщения в группу group1 непосредственно при подключении с помощью этого URL-адреса клиентского доступа

     var url = service.GetClientAccessUri(roles: new string[] { "webpubsub.sendToGroup.group1" });
     

   • Настройка группы group1 , присоединенной клиентом после подключения с помощью этого URL-адреса клиентского доступа

     var url = service.GetClientAccessUri(groups: new string[] { "group1" });
     

Python

1. Следуйте инструкциям по началу работы с пакетом WebPubSubServiceClient SDK для сервера, чтобы создать объектservice

2. Создайте URL-адрес клиентского доступа путем вызова WebPubSubServiceClient.get_client_access_token:

   • Создание маркера доступа клиента

     # for web pubsub native clients
     token = service.get_client_access_token();
     
     # for mqtt clients
     token = service.get_client_access_token(client_protocol="MQTT")
     

   • Настройка идентификатора пользователя

     token = service.get_client_access_token(user_id="user1")
     

   • Настройка времени существования маркера

     token = service.get_client_access_token(minutes_to_expire=5)
     

   • Настройка роли, которая может присоединиться group1 непосредственно при подключении с помощью этого URL-адреса клиентского доступа

     token = service.get_client_access_token(roles=["webpubsub.joinLeaveGroup.group1"])
     

   • Настройка роли, которую клиент может отправлять сообщения в группу group1 непосредственно при подключении с помощью этого URL-адреса клиентского доступа

     token = service.get_client_access_token(roles=["webpubsub.sendToGroup.group1"])
     

   • Настройка группы group1 , присоединенной клиентом после подключения с помощью этого URL-адреса клиентского доступа

     token = service.get_client_access_token(groups=["group1"])
     

Java

1. Следуйте инструкциям по началу работы с пакетом WebPubSubServiceClient SDK для сервера, чтобы создать объектservice

2. Создайте URL-адрес клиентского доступа путем вызова WebPubSubServiceClient.getClientAccessToken:

   • Создание маркера доступа клиента для собственных клиентов Web PubSub

     GetClientAccessTokenOptions option = new GetClientAccessTokenOptions();
     WebPubSubClientAccessToken token = service.getClientAccessToken(option);
     

   • Создание маркера доступа клиента для клиентов MQTT

     GetClientAccessTokenOptions option = new GetClientAccessTokenOptions();
     option.setWebPubSubClientProtocol(WebPubSubClientProtocol.MQTT);
     WebPubSubClientAccessToken token = service.getClientAccessToken(option);
     

   • Настройка идентификатора пользователя

   GetClientAccessTokenOptions option = new GetClientAccessTokenOptions();
   option.setUserId(id);
   WebPubSubClientAccessToken token = service.getClientAccessToken(option);
   

   • Настройка времени существования маркера

     GetClientAccessTokenOptions option = new GetClientAccessTokenOptions();
     option.setExpiresAfter(Duration.ofDays(1));
     WebPubSubClientAccessToken token = service.getClientAccessToken(option);
     

   • Настройка роли, которая может присоединиться group1 непосредственно при подключении с помощью этого URL-адреса клиентского доступа

     GetClientAccessTokenOptions option = new GetClientAccessTokenOptions();
     option.addRole("webpubsub.joinLeaveGroup.group1");
     WebPubSubClientAccessToken token = service.getClientAccessToken(option);
     

   • Настройка роли, которую клиент может отправлять сообщения в группу group1 непосредственно при подключении с помощью этого URL-адреса клиентского доступа

     GetClientAccessTokenOptions option = new GetClientAccessTokenOptions();
     option.addRole("webpubsub.sendToGroup.group1");
     WebPubSubClientAccessToken token = service.getClientAccessToken(option);
     

   • Настройка группы group1 , присоединенной клиентом после подключения с помощью этого URL-адреса клиентского доступа

     GetClientAccessTokenOptions option = new GetClientAccessTokenOptions();
     option.setGroups(Arrays.asList("group1")),
     WebPubSubClientAccessToken token = service.getClientAccessToken(option);
     

В реальном коде у нас обычно есть серверная сторона для размещения логики, создающей URL-адрес клиентского доступа. При появлении запроса клиента на стороне сервера можно использовать общий рабочий процесс проверки подлинности и авторизации для проверки клиентского запроса. Только допустимые запросы клиента могут вернуть URL-адрес доступа клиента.

Создание из REST API :generateToken

Вы также можете использовать идентификатор Microsoft Entra и создать маркер, вызвав REST API создания маркера клиента.

Примечание.

Web PubSub не рекомендует создавать маркеры идентификатора Microsoft Entra для субъектов-служб Microsoft Entra ID вручную. Это связано с тем, что каждый маркер идентификатора Microsoft Entra является коротким сроком действия, обычно истекает в течение одного часа. После этого необходимо вручную создать заменяющий маркер идентификатора Microsoft Entra. Вместо этого используйте наши пакеты SDK, которые автоматически создают и заменяют истекшие маркеры идентификатора Microsoft Entra.

1. Выполните авторизацию из приложения , чтобы включить идентификатор Microsoft Entra.

2. Получите токен Microsoft Entra.

3. Используйте маркер Microsoft Entra для вызова :generateToken.

4. Соберите следующие сведения:

   Value name	Получение значения
   TenantId	TenantId — это значение идентификатора каталога (клиента) на панели обзора зарегистрированного приложения.
   ClientId	ClientId — это значение идентификатора приложения (клиента) в области обзора зарегистрированного приложения.
   ClientSecret	ClientSecret — это значение секрета клиента, который вы только что добавили на шаге 1.

5. Получение маркера идентификатора Microsoft Entra из платформа удостоверений Майкрософт

   Мы используем средство 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 отправляет запрос POST в конечную точку удостоверений Майкрософт, чтобы вернуть маркер идентификатора Microsoft Entra. В ответе отображается маркер идентификатора Microsoft Entra в access_token поле. Скопируйте и сохраните его для последующего использования.

6. Вызов маркера идентификатора Microsoft Entra :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"
   }