Compartilhar via

Como gerar a URL de acesso para clientes

  • Artigo

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

A 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.

Copiar do portal do Azure

Na guia “Chaves” no portal do Azure, há uma ferramenta “Gerador de URL para cliente” para gerar rapidamente uma URL de acesso para cliente para você, conforme mostrado no diagrama a seguir. A entrada de valores aqui não é armazenada.

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

Captura de tela do Gerador de URL do Cliente do Web PubSub.

Gerar do SDK de serviço

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

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

  2. Gere a URL de acesso para cliente chamando WebPubSubServiceClient.getClientAccessToken:

    • Gerar o token de acesso do cliente

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

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

    • Configurar a ID do 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 pode unir o grupo group1 diretamente quando ele se conecta usando essa URL de acesso para cliente

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

    • Configurar uma função que permita ao cliente enviar mensagens para o grupo group1 diretamente quando se conectar usando essa URL de acesso para cliente

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

    • Configurar um grupo group1 que o cliente ingressa depois de se conectar usando essa URL de acesso para cliente

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

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

Gerar a partir da API REST :generateToken

Você também pode usar o Microsoft Entra ID e gerar o token invocando a API REST de Geração de Token de Cliente.

Observação

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

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

  2. Obtenha o token do Microsoft Entra.

  3. Usar o token do Microsoft Entra para invocar :generateToken.

  4. Reúna as seguintes informações:

    Nome do valor Como obter o valor
    TenantId TenantId é o valor da ID do diretório (locatário) no painel Visão geral do aplicativo que você registrou.
    ClientId ClientId é o valor da 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 nº 1

  5. Obter o token do Microsoft Entra ID da plataforma de identidade da Microsoft

    Usamos a ferramenta CURL para mostrar como invocar as APIs REST. A ferramenta é agrupada no Windows 10/11 e você pode instalar a ferramenta após a instalação do 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 ao ponto de extremidade de identidade da Microsoft para obter o Token do Microsoft Entra ID de volta. Na resposta, você verá o token do Microsoft Entra ID no campo access_token. Copie e armazene-a para uso posterior.

  6. Usar o token do Microsoft Entra ID 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, acrescente o parâmetro 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"

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

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