Como gerar URL de acesso para clientes

Um cliente, seja um navegador 💻, um aplicativo 📱móvel ou um dispositivo 💡IoT, usa uma URL de Acesso para Cliente para se conectar e autenticar com seu recurso.

O URL segue o padrão abaixo:

• Para clientes MQTT, é wss://<service_name>.webpubsub.azure.com/clients/mqtt/hubs/<hub_name>?access_token=<token>.
• Para todos os outros clientes, é wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>.

Este artigo mostra várias maneiras de obter a URL de Acesso para Cliente.

• Para início rápido, copie um do portal do Azure
• Para desenvolvimento, gere o valor usando o SDK do servidor Web PubSub
• Se você estiver usando o Microsoft Entra ID, também poderá invocar a API REST Gerar Token de Cliente

Copiar do portal do Azure

Na guia Chaves no portal do Azure, há uma ferramenta Gerador de URL do Cliente para gerar rapidamente uma URL de Acesso para Cliente para você, conforme mostrado no diagrama a seguir. Os valores inseridos aqui não são armazenados.

Observe que, para clientes MQTT, você deve selecionar "Cliente MQTT" no menu suspenso na frente da caixa de texto "URL de Acesso para Cliente".

Gerar a partir do SDK do serviço

A mesma URL de Acesso para Cliente pode ser gerada usando o SDK do servidor Web PubSub.

JavaScript

1. Siga Introdução ao SDK do servidor para criar um WebPubSubServiceClient objeto service

2. Gere URL de Acesso para Cliente chamando WebPubSubServiceClient.getClientAccessToken:

   • Gerar token de acesso para cliente

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

   • Configurar ID de usuário

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

   • Configurar o tempo de vida do token

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

   • Configurar uma função que possa ingressar diretamente no grupo group1 quando ele se conectar usando essa URL de Acesso para Cliente

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

   • Configure uma função para a qual o cliente possa enviar mensagens diretamente ao grupo group1 quando se conectar usando essa URL de Acesso para Cliente

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

   • Configurar um grupo group1 ao qual o cliente ingressa depois de se conectar usando essa URL de Acesso para Cliente

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

C#

1. Siga Introdução ao SDK do servidor para criar um WebPubSubServiceClient objeto service

2. Gere URL de Acesso para Cliente chamando WebPubSubServiceClient.GetClientAccessUri:

   • Gerar token de acesso para cliente

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

   • Configurar ID de usuário

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

   • Configurar o tempo de vida do token

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

   • Configurar uma função que possa ingressar diretamente no grupo group1 quando ele se conectar usando essa URL de Acesso para Cliente

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

   • Configure uma função para a qual o cliente possa enviar mensagens diretamente ao grupo group1 quando se conectar usando essa URL de Acesso para Cliente

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

   • Configurar um grupo group1 ao qual o cliente ingressa depois de se conectar usando essa URL de Acesso para Cliente

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

Python

1. Siga Introdução ao SDK do servidor para criar um WebPubSubServiceClient objeto service

2. Gere URL de Acesso para Cliente chamando WebPubSubServiceClient.get_client_access_token:

   • Gerar token de acesso para cliente

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

   • Configurar ID de usuário

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

   • Configurar o tempo de vida do token

     token = service.get_client_access_token(minutes_to_expire=5)
     

   • Configurar uma função que possa ingressar diretamente no grupo group1 quando ele se conectar usando essa URL de Acesso para Cliente

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

   • Configure uma função para a qual o cliente possa enviar mensagens diretamente ao grupo group1 quando se conectar usando essa URL de Acesso para Cliente

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

   • Configurar um grupo group1 ao qual o cliente ingressa depois de se conectar usando essa URL de Acesso para Cliente

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

Java

1. Siga Introdução ao SDK do servidor para criar um WebPubSubServiceClient objeto service

2. Gere URL de Acesso para Cliente chamando WebPubSubServiceClient.getClientAccessToken:

   • Gerar token de acesso de cliente para clientes nativos do Web PubSub

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

   • Gerar token de acesso de cliente para clientes MQTT

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

   • Configurar ID de usuário

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

   • Configurar o tempo de vida do token

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

   • Configurar uma função que possa ingressar diretamente no grupo group1 quando ele se conectar usando essa URL de Acesso para Cliente

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

   • Configure uma função para a qual o cliente possa enviar mensagens diretamente ao grupo group1 quando se conectar usando essa URL de Acesso para Cliente

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

   • Configurar um grupo group1 ao qual o cliente ingressa depois de se conectar usando essa URL de Acesso para Cliente

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

No código do mundo real, geralmente temos um lado do servidor para hospedar a lógica que gera a URL de Acesso para Cliente. Quando uma solicitação de cliente chega, o lado do servidor pode usar o fluxo de trabalho geral de autenticação/autorização para validar a solicitação do cliente. Somente solicitações de cliente válidas podem obter a URL de Acesso para Cliente de volta.

Gerar a partir da API REST :generateToken

Você também pode usar o Microsoft Entra ID e gerar o token invocando Generate Client Token REST API.

Nota

O Web PubSub não recomenda que você crie tokens de ID do Microsoft Entra para entidades de serviço do Microsoft Entra ID manualmente. Isso ocorre porque cada token de ID do Microsoft Entra é de curta duração, normalmente expirando dentro de uma hora. Após esse período, você deve gerar manualmente um token de ID do Microsoft Entra de substituição. Em vez disso, use nossos SDKs que geram e substituem automaticamente tokens de ID do Microsoft Entra expirados para você.

1. Siga Autorizar do aplicativo para habilitar o Microsoft Entra ID.

2. Obtenha o token Microsoft Entra.

3. Use o token do Microsoft Entra para invocar :generateTokeno .

4. Recolha as seguintes informações:

   Nome do valor	Como obter o valor
   TenantId	TenantId é o valor de Directory (tenant) ID no painel Visão geral do aplicativo que você registrou.
   ClientId	ClientId é o valor do ID do aplicativo (cliente) do painel Visão geral do aplicativo que você registrou.
   ClientSecret	ClientSecret é o valor do segredo do cliente que você acabou de adicionar na etapa #1

5. Obtenha o token Microsoft Entra ID da plataforma de identidade da Microsoft

   Usamos a ferramenta CURL para mostrar como invocar as APIs REST. A ferramenta está incluída no Windows 10/11, e você pode instalá-la após Instalar o 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"
   
   

   O comando curl acima envia uma solicitação POST para o ponto de extremidade de identidade da Microsoft para obter o token de ID do Microsoft Entra de volta. Na resposta, você verá o token de ID do Microsoft Entra no access_token campo. Copie e guarde-o para utilização posterior.

6. Use o token de ID do Microsoft Entra para invocar :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"
   

   Se você precisar gerar o token para clientes MQTT, anexe o clientType=mqtt parâmetro à 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"
   

   Depois de executar o cURL comando, você deve obter uma resposta como esta:

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