Come generare l'URL di accesso client per i client

Un client, ad esempio un browser 💻, un'app per dispositivi mobili 📱 o un dispositivo IoT 💡, usa un URL di accesso client per connettersi ed eseguire l'autenticazione con la risorsa.

L'URL segue il criterio seguente:

• Per i client MQTT, è wss://<service_name>.webpubsub.azure.com/clients/mqtt/hubs/<hub_name>?access_token=<token>.
• Per tutti gli altri client, è wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>.

Questo articolo illustra diversi modi per ottenere l'URL di accesso client.

• Per iniziare rapidamente, copiarne uno dal portale di Azure
• Per lo sviluppo, generare il valore usando Web PubSub server SDK
• Se si usa Microsoft Entra ID, è anche possibile richiamare l'API REST Generate Client Token

Copiare dal portale di Azure

Nella scheda Chiavi nel portale di Azure è disponibile uno strumento Generatore URL client per generare rapidamente un URL di accesso client, come illustrato nel diagramma seguente. I valori inseriti qui non vengono archiviati.

Si noti che per i client MQTT è necessario selezionare "Client MQTT" nel menu a discesa davanti alla casella di testo "URL di accesso client".

Generare dall'SDK del servizio

Lo stesso URL di accesso client può essere generato tramite Web PubSub server SDK.

JavaScript

1. Seguire Introduzione all'SDK del server per creare un oggetto WebPubSubServiceClient per service

2. Generare l'URL di accesso client chiamando WebPubSubServiceClient.getClientAccessToken:

   • Generare un token di accesso client

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

   • Configurare l'ID utente

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

   • Configurare la durata del token

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

   • Configurare un ruolo che possa partecipare al gruppo group1 direttamente quando si connette usando questo URL di accesso client

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

   • Configurare un ruolo che consenta al client di inviare messaggi al gruppo group1 direttamente quando si connette usando questo URL di accesso client

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

   • Configurare un gruppo group1 a cui il client può partecipare dopo la connessione tramite questo URL di accesso client

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

C#

1. Seguire Introduzione all'SDK del server per creare un oggetto WebPubSubServiceClient per service

2. Generare l'URL di accesso client chiamando WebPubSubServiceClient.GetClientAccessUri:

   • Generare un token di accesso client

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

   • Configurare l'ID utente

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

   • Configurare la durata del token

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

   • Configurare un ruolo che possa partecipare al gruppo group1 direttamente quando si connette usando questo URL di accesso client

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

   • Configurare un ruolo che consenta al client di inviare messaggi al gruppo group1 direttamente quando si connette usando questo URL di accesso client

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

   • Configurare un gruppo group1 a cui il client può partecipare dopo la connessione tramite questo URL di accesso client

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

Python

1. Seguire Introduzione all'SDK del server per creare un oggetto WebPubSubServiceClient per service

2. Generare l'URL di accesso client chiamando WebPubSubServiceClient.get_client_access_token:

   • Generare un token di accesso client

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

   • Configurare l'ID utente

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

   • Configurare la durata del token

     token = service.get_client_access_token(minutes_to_expire=5)
     

   • Configurare un ruolo che possa partecipare al gruppo group1 direttamente quando si connette usando questo URL di accesso client

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

   • Configurare un ruolo che consenta al client di inviare messaggi al gruppo group1 direttamente quando si connette usando questo URL di accesso client

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

   • Configurare un gruppo group1 a cui il client può partecipare dopo la connessione tramite questo URL di accesso client

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

Java

1. Seguire Introduzione all'SDK del server per creare un oggetto WebPubSubServiceClient per service

2. Generare l'URL di accesso client chiamando WebPubSubServiceClient.getClientAccessToken:

   • Generare un token di accesso client per i client nativi Web PubSub

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

   • Generare un token di accesso client per i client MQTT

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

   • Configurare l'ID utente

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

   • Configurare la durata del token

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

   • Configurare un ruolo che possa partecipare al gruppo group1 direttamente quando si connette usando questo URL di accesso client

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

   • Configurare un ruolo che consenta al client di inviare messaggi al gruppo group1 direttamente quando si connette usando questo URL di accesso client

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

   • Configurare un gruppo group1 a cui il client può partecipare dopo la connessione tramite questo URL di accesso client

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

Nel codice reale è in genere disponibile un lato server per ospitare la logica che genera l'URL di accesso client. Quando arriva una richiesta client, il lato server può usare il flusso di lavoro di autenticazione/autorizzazione generale per convalidare la richiesta client. Solo le richieste client valide possono ottenere l'URL di accesso client.

Generare dall'API REST :generateToken

È anche possibile usare Microsoft Entra ID e generare il token richiamando l'API REST Generate Client Token.

Nota

Web PubSub non consiglia di creare manualmente token di Microsoft Entra ID per le entità servizio di Microsoft Entra ID. Ciò è dovuto al fatto che ogni token di Microsoft Entra ID è di breve durata e scade in genere entro un'ora. Dopo la scadenza è necessario generare manualmente un token di Microsoft Entra ID sostitutivo. Usare invece gli SDK che generano e sostituiscono automaticamente i token di Microsoft Entra ID scaduti.

1. Seguire Autorizzare dall'applicazione per abilitare Microsoft Entra ID.

2. Ottenere il token di Microsoft Entra.

3. Usare il token Microsoft Entra per richiamare :generateToken.

4. Raccogliere le seguenti informazioni:

   Nome valore	Come ottenere il valore
   TenantId	TenantId è il valore di ID directory (tenant) nel riquadro Panoramica dell'applicazione registrata.
   ClientId	ClientId è il valore di ID applicazione (client) dal riquadro Panoramica dell'applicazione registrata.
   ClientSecret	ClientSecret è il valore del segreto client appena aggiunto nel passaggio 1

5. Ottenere il token di Microsoft Entra ID da Microsoft Identity Platform

   Per illustrare come richiamare le API REST, viene usato lo strumento CURL. Lo strumento è incluso in Windows 10/11 ed è possibile installarlo seguendo la procedura per Installare CURL.

   # set neccessory 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"
   
   

   Il comando CURL precedente invia una richiesta POST all'endpoint di identità Microsoft per ottenere il token di Microsoft Entra ID. Nella risposta viene visualizzato il token di Microsoft Entra ID nel campo access_token. Copiarlo e archiviarlo per usarlo in seguito.

6. Usare il token di Microsoft Entra ID per richiamare :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 è necessario generare il token per i client MQTT, aggiungere il parametro clientType=mqtt all'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"
   

   Dopo aver eseguito il comando cURL, si dovrebbe ottenere una risposta simile alla seguente:

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