How to generate client access URL for the clients

A client, be it a browser 💻, a mobile app 📱, or an IoT device 💡, uses a Client Access URL to connect and authenticate with your resource. This URL follows a pattern of wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. This article shows you several ways to get the Client Access URL.

• For quick start, copy one from the Azure portal
• For development, generate the value using Web PubSub server SDK
• If you're using Microsoft Entra ID, you can also invoke the Generate Client Token REST API

Copy from the Azure portal

In the Keys tab in Azure portal, there's a Client URL Generator tool to quickly generate a Client Access URL for you, as shown in the following diagram. Values input here aren't stored.

Generate from service SDK

The same Client Access URL can be generated by using the Web PubSub server SDK.

JavaScript

1. Follow Getting started with server SDK to create a WebPubSubServiceClient object service

2. Generate Client Access URL by calling WebPubSubServiceClient.getClientAccessToken:

   • Configure user ID

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

   • Configure the lifetime of the token

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

   • Configure a role that can join group group1 directly when it connects using this Client Access URL

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

   • Configure a role that the client can send messages to group group1 directly when it connects using this Client Access URL

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

   • Configure a group group1 that the client joins once it connects using this Client Access URL

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

C#

1. Follow Getting started with server SDK to create a WebPubSubServiceClient object service

2. Generate Client Access URL by calling WebPubSubServiceClient.GetClientAccessUri:

   • Configure user ID

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

   • Configure the lifetime of the token

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

   • Configure a role that can join group group1 directly when it connects using this Client Access URL

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

   • Configure a role that the client can send messages to group group1 directly when it connects using this Client Access URL

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

   • Configure a group group1 that the client joins once it connects using this Client Access URL

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

Python

1. Follow Getting started with server SDK to create a WebPubSubServiceClient object service

2. Generate Client Access URL by calling WebPubSubServiceClient.get_client_access_token:

   • Configure user ID

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

   • Configure the lifetime of the token

     token = service.get_client_access_token(minutes_to_expire=5)
     

   • Configure a role that can join group group1 directly when it connects using this Client Access URL

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

   • Configure a role that the client can send messages to group group1 directly when it connects using this Client Access URL

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

   • Configure a group group1 that the client joins once it connects using this Client Access URL

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

Java

1. Follow Getting started with server SDK to create a WebPubSubServiceClient object service

2. Generate Client Access URL by calling WebPubSubServiceClient.getClientAccessToken:

   • Configure user ID

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

   • Configure the lifetime of the token

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

   • Configure a role that can join group group1 directly when it connects using this Client Access URL

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

   • Configure a role that the client can send messages to group group1 directly when it connects using this Client Access URL

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

   • Configure a group group1 that the client joins once it connects using this Client Access URL

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

In real-world code, we usually have a server side to host the logic generating the Client Access URL. When a client request comes in, the server side can use the general authentication/authorization workflow to validate the client request. Only valid client requests can get the Client Access URL back.

Invoke the Generate Client Token REST API

You can enable Microsoft Entra ID in your service and use the Microsoft Entra token to invoke Generate Client Token rest API to get the token for the client to use.

1. Follow Authorize from application to enable Microsoft Entra ID.

2. Follow Get Microsoft Entra token to get the Microsoft Entra token with Postman.

3. Use the Microsoft Entra token to invoke :generateToken with Postman:

   Note

   Please use the latest version of Postman. Old versions of Postman have some issue supporting colon : in path.

   1. For the URI, enter https://{Endpoint}/api/hubs/{hub}/:generateToken?api-version=2022-11-01

   2. On the Auth tab, select Bearer Token and paste the Microsoft Entra token fetched in the previous step

   3. Select Send and you see the Client Access Token in the response:

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

4. The Client Access URI is in the format of wss://<endpoint>/client/hubs/<hub_name>?access_token=<token>