Partager via

Guide pratique pour générer l’URL d’accès client pour les clients

  • Article

Un client, qu’il s’agisse d’un navigateur 💻, d’une application mobile 📱 ou d’un appareil IoT 💡, utilise une URL d’accès au client pour se connecter et s’authentifier auprès de votre ressource.

L’URL suit le modèle ci-dessous :

  • Pour les clients MQTT, il s’agit de wss://<service_name>.webpubsub.azure.com/clients/mqtt/hubs/<hub_name>?access_token=<token>.
  • Pour tous les autres clients, il s’agit de wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>.

Cet article montre plusieurs manières d’obtenir l’URL d’accès client.

Copier à partir du portail Azure

Sous l’onglet Clés du portail Azure, il existe un outil Générateur d’URL client qui vous permet de générer rapidement une URL d’accès client, comme illustré dans le diagramme suivant. Les valeurs entrées ici ne sont pas stockées.

Notez que pour les clients MQTT, vous devez sélectionner « Client MQTT » dans le menu déroulant devant la zone de texte « URL d’accès client ».

Capture d’écran du générateur d’URL du client Web PubSub.

Générer à partir du kit SDK de service

La même URL d’accès client peut être générée à l’aide du kit SDK du serveur Web PubSub.

  1. Suivez les instructions fournies dans Bien démarrer avec le kit de développement logiciel (SDK) de serveur pour créer un objet WebPubSubServiceClient service.

  2. Générez l’URL d’accès client en appelant WebPubSubServiceClient.getClientAccessToken :

    • Générer le jeton d’accès client

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

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

    • Configurer l’ID utilisateur

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

    • Configurer la durée de vie du jeton

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

    • Configurer un rôle qui peut rejoindre le groupe group1 directement lorsqu’il se connecte à l’aide de cette URL d’accès client

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

    • Configurer un rôle précisant que le client peut envoyer des messages au groupe group1 directement lorsqu’il se connecte à l’aide de cette URL d’accès client

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

    • Configurer un groupe group1 que le client rejoint une fois qu’il se connecte à l’aide de cette URL d’accès client

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

Dans le code réel, nous avons généralement un côté serveur pour héberger la logique générant l’URL d’accès client. Lorsqu’une requête de client arrive, le côté serveur peut utiliser le flux de travail d’authentification/autorisation général pour valider la requête du client. Seules les requêtes de client valides peuvent récupérer l’URL d’accès client.

Générer à partir de l’API REST :generateToken

Vous pouvez également utiliser Microsoft Entra ID et générer le jeton en appelant l’API REST Générer un jeton client.

Remarque

Web PubSub ne vous recommande pas de créer manuellement des jetons Microsoft Entra ID pour les principaux de service Microsoft Entra ID. C’est parce que chaque jeton Microsoft Entra ID est de courte durée et expire généralement dans l’heure. Au-delà de ce délai, vous devez générer manuellement un jeton Microsoft Entra ID de remplacement. Utilisez plutôt nos SDK qui génèrent et remplacent automatiquement les jetons Microsoft Entra ID expirés pour vous.

  1. Suivez les instructions fournies dans Autoriser à partir de l’application pour activer Microsoft Entra ID.

  2. Obtenez le jeton Microsoft Entra.

  3. Utilisez le jeton Microsoft Entra ID pour appeler :generateToken.

  4. Rassemblez les informations suivantes :

    Nom de la valeur Comment obtenir la valeur
    TenantId TenantId est la valeur de l’ID d’annuaire (locataire) dans le volet Vue d’ensemble de l’application que vous avez inscrite.
    ClientId ClientId est la valeur de l’ID d’application (client) dans le volet Vue d’ensemble de l’application que vous avez inscrite.
    ClientSecret ClientSecret est la valeur de la clé secrète client que vous venez d’ajouter à l’étape 1

  5. Obtenir le jeton Microsoft Entra ID à partir de la Plateforme d’identités Microsoft

    Nous utilisons l’outil CURL pour montrer comment appeler les API REST. L’outil est regroupé dans Windows 10/11 et vous pouvez installer l’outil en suivant Installer 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"

    La commande curl ci-dessus envoie une requête POST au point de terminaison d’identité Microsoft pour récupérer le jeton Microsoft Entra ID. Dans la réponse, vous voyez le jeton Microsoft Entra ID dans le champ access_token. Copiez-la et conservez-la, vous en aurez besoin par la suite.

  6. Utiliser le jeton Microsoft Entra ID pour appeler :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"

    Si vous devez générer le jeton pour les clients MQTT, ajoutez le paramètre clientType=mqtt à l’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"

    Après avoir exécuté la commande cURL, vous devez obtenir une réponse semblable à ceci :

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