Generieren der Clientzugriffs-URL für die Clients

Ein Client, sei es ein Browser 💻, eine mobile App 📱 oder ein IoT-Gerät 💡, verwendet eine Clientzugriffs-URL, um eine Verbindung mit Ihrer Ressource herzustellen und sich zu authentifizieren.

Die URL hat das folgende Muster:

• Für MQTT-Clients: wss://<service_name>.webpubsub.azure.com/clients/mqtt/hubs/<hub_name>?access_token=<token>
• Für alle anderen Clients: wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>

In diesem Artikel werden verschiedene Möglichkeiten zum Abrufen der Clientzugriffs-URL beschrieben.

• Kopieren Sie eine aus dem Azure-Portal, um schnell loszulegen.
• Generieren Sie für die Entwicklung den Wert mithilfe des Web PubSub Server SDK.
• Wenn Sie Microsoft Entra-ID verwenden, können Sie auch die REST-API zum Generieren von Clienttoken aufrufen.

Kopieren aus dem Azure-Portal

Auf der Registerkarte „Schlüssel“ im Azure-Portal gibt es ein Client-URL-Generatortool, das schnell eine Clientzugriffs-URL für Sie generiert, wie in der folgenden Abbildung gezeigt. Die hier eingegebenen Werte werden nicht gespeichert.

Beachten Sie, dass Sie für MQTT-Clients im Dropdownmenü vor dem Textfeld „Clientzugriffs-URL“ die Option „MQTT-Client“ auswählen sollten.

Generieren über das Dienst-SDK

Die gleiche Clientzugriffs-URL kann mithilfe des Web PubSub Server SDK generiert werden.

JavaScript

1. Befolgen Sie die ersten Schritte mit dem Server SDK, um das WebPubSubServiceClient-Objekt service zu erstellen.

2. Generieren Sie die Clientzugriffs-URL durch Aufrufen von WebPubSubServiceClient.getClientAccessToken:

   • Generieren eines Clientzugriffstokens

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

   • Konfigurieren der Benutzer-ID

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

   • Konfigurieren der Lebensdauer des Tokens

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

   • Konfigurieren einer Rolle, die der Gruppe group1 direkt beitreten kann, wenn sie eine Verbindung mithilfe dieser Clientzugriffs-URL herstellt

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

   • Konfigurieren einer Rolle, mit der der Client Nachrichten direkt an die Gruppe group1 senden kann, wenn er eine Verbindung mithilfe dieser Clientzugriffs-URL herstellt

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

   • Konfigurieren der Gruppe group1, der der Client beitritt, wenn er eine Verbindung mithilfe dieser Clientzugriffs-URL herstellt

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

C#

1. Befolgen Sie die ersten Schritte mit dem Server SDK, um das WebPubSubServiceClient-Objekt service zu erstellen.

2. Generieren Sie die Clientzugriffs-URL durch Aufrufen von WebPubSubServiceClient.GetClientAccessUri:

   • Generieren eines Clientzugriffstokens

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

   • Konfigurieren der Benutzer-ID

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

   • Konfigurieren der Lebensdauer des Tokens

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

   • Konfigurieren einer Rolle, die der Gruppe group1 direkt beitreten kann, wenn sie eine Verbindung mithilfe dieser Clientzugriffs-URL herstellt

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

   • Konfigurieren einer Rolle, mit der der Client Nachrichten direkt an die Gruppe group1 senden kann, wenn er eine Verbindung mithilfe dieser Clientzugriffs-URL herstellt

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

   • Konfigurieren der Gruppe group1, der der Client beitritt, wenn er eine Verbindung mithilfe dieser Clientzugriffs-URL herstellt

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

Python

1. Befolgen Sie die ersten Schritte mit dem Server SDK, um das WebPubSubServiceClient-Objekt service zu erstellen.

2. Generieren Sie die Clientzugriffs-URL durch Aufrufen von WebPubSubServiceClient.get_client_access_token:

   • Generieren eines Clientzugriffstokens

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

   • Konfigurieren der Benutzer-ID

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

   • Konfigurieren der Lebensdauer des Tokens

     token = service.get_client_access_token(minutes_to_expire=5)
     

   • Konfigurieren einer Rolle, die der Gruppe group1 direkt beitreten kann, wenn sie eine Verbindung mithilfe dieser Clientzugriffs-URL herstellt

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

   • Konfigurieren einer Rolle, mit der der Client Nachrichten direkt an die Gruppe group1 senden kann, wenn er eine Verbindung mithilfe dieser Clientzugriffs-URL herstellt

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

   • Konfigurieren der Gruppe group1, der der Client beitritt, wenn er eine Verbindung mithilfe dieser Clientzugriffs-URL herstellt

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

Java

1. Befolgen Sie die ersten Schritte mit dem Server SDK, um das WebPubSubServiceClient-Objekt service zu erstellen.

2. Generieren Sie die Clientzugriffs-URL durch Aufrufen von WebPubSubServiceClient.getClientAccessToken:

   • Generieren eines Clientzugriffstokens für native Web PubSub-Clients

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

   • Generieren eines Clientzugriffstokens für MQTT-Clients

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

   • Konfigurieren der Benutzer-ID

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

   • Konfigurieren der Lebensdauer des Tokens

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

   • Konfigurieren einer Rolle, die der Gruppe group1 direkt beitreten kann, wenn sie eine Verbindung mithilfe dieser Clientzugriffs-URL herstellt

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

   • Konfigurieren einer Rolle, mit der der Client Nachrichten direkt an die Gruppe group1 senden kann, wenn er eine Verbindung mithilfe dieser Clientzugriffs-URL herstellt

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

   • Konfigurieren der Gruppe group1, der der Client beitritt, wenn er eine Verbindung mithilfe dieser Clientzugriffs-URL herstellt

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

Im realen Code verfügen wir in der Regel über einen Server zum Hosten der Logik, die die Clientzugriffs-URL generiert. Wenn eine Clientanforderung eingeht, kann der Server den allgemeinen Authentifizierungs-/Autorisierungsworkflow verwenden, um die Clientanforderung zu überprüfen. Nur gültige Clientanforderungen können die Clientzugriffs-URL wieder abrufen.

Generieren aus der REST-API :generateToken

Sie können auch Microsoft Entra ID verwenden und das Token generieren, indem Sie Clienttoken-REST-API generieren aufrufen.

Hinweis

Web PubSub empfiehlt nicht, Microsoft Entra ID-Token für Microsoft Entra ID-Dienstprinzipale manuell zu erstellen. Der Grund dafür ist, dass jedes Microsoft Entra ID-Token kurzlebig ist und normalerweise innerhalb einer Stunde abläuft. Nach diesem Zeitpunkt müssen Sie manuell ein Microsoft Entra ID-Ersatztoken generieren. Verwenden Sie stattdessen unsere SDKs, die abgelaufene Microsoft Entra ID-Token automatisch für Sie generieren und ersetzen.

1. Führen Sie die Schritte zum Autorisieren über die Anwendung aus, um Microsoft Entra ID zu aktivieren.

2. Rufen Sie das Microsoft Entra-Token ab.

3. Verwenden Sie das Microsoft Entra-Token zum Aufrufen von :generateToken.

4. Sammeln Sie die folgenden Informationen:

   Name des Werts	So erhalten Sie den Wert
   TenantId	TenantId ist der Wert der Verzeichnis-ID (Mandanten-ID) im Bereich Übersicht der von Ihnen registrierten Anwendung.
   ClientId	Client_id ist der Wert der Anwendungs-ID (Client-ID) aus dem Bereich Übersicht der von Ihnen registrierten Anwendung.
   Geheimer Clientschlüssel	ClientSecret ist der Wert des geheimen Clientschlüssels, den Sie soeben in Schritt 1 hinzugefügt haben.

5. Abrufen des Microsoft Entra ID-Tokens von der Microsoft Identity Platform

   Wir verwenden das CURL-Tool, um zu zeigen, wie die REST-APIs aufgerufen werden. Das Tool ist in Windows 10/11 gebündelt. Folgen Sie zum Installieren den Anweisungen unter Installieren von 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"
   
   

   Der obige curl-Befehl sendet eine POST-Anforderung an den Microsoft Identity-Endpunkt, um das Microsoft Entra ID-Token zurückzuerhalten. In der Antwort wird das Microsoft Entra ID-Token im Feld access_token angezeigt. Kopieren und speichern Sie die URL zur späteren Verwendung.

6. Verwenden des Microsoft Entra ID-Tokens zum Aufrufen von :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"
   

   Wenn Sie Token für MQTT-Clients generieren möchten, fügen Sie den Abfrageparameter clientType=mqtt an die URL an:

   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"
   

   Nachdem Sie den Befehl cURL ausgeführt haben, sollten Sie eine Antwort ähnlich der folgenden erhalten:

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