Skip to content

Commit a4eed7d

Browse files
vicancyvicancy
authored
Add doc for client access url
1 parent a263bd4 commit a4eed7d

File tree

3 files changed

+178
-5
lines changed

3 files changed

+178
-5
lines changed

‎articles/azure-web-pubsub/howto-generate-client-access-url.md

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
---
2+
title: How to generate client access URL for the clients
3+
description: How to generate client access URL for the clients
4+
author: vicancy
5+
6+
ms.author: lianwei
7+
ms.date: 04/25/2023
8+
ms.service: azure-web-pubsub
9+
ms.topic: how-to
10+
---
11+
12+
# How to generate client access URL for the clients
13+
14+
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 artcile shows you several ways to get the Client Access URL.
15+
16+
- For quick start, copy one from the Azure portal
17+
- For development, generate the value using [Web PubSub server SDK](./reference-server-sdk-js.md)
18+
- If you are using Azure AD, you can also invoke the [Generate Client Token REST API](/rest/api/webpubsub/dataplane/web-pub-sub/generate-client-token)
19+
20+
## Copy from the Azure portal
21+
In the Keys tab in Azure portal, there is a Client URL Generator tool to quickly generate a Client Access URL for you, as shown in the following diagram. Please note that values input here are not stored.
22+
23+
![The diagram shows how to get client access url.](./media/howto-websocket-connect/generate-client-url.png)
24+
25+
## Generate from service SDK
26+
The same Client Access URL can be generated by using the Web PubSub server SDK.
27+
28+
# [JavaScript](#tab/javascript)
29+
30+
1. Follow [./reference-server-sdk-js.md#getting-started] to create a `WebPubSubServiceClient` object `service`
31+
32+
2. Generate Client Access URL by calling `WebPubSubServiceClient.getClientAccessToken`:
33+
* Configure user ID
34+
```js
35+
let token = await serviceClient.getClientAccessToken({ userId: "user1" });
36+
```
37+
* Configure the lifetime of the token
38+
```js
39+
let token = await serviceClient.getClientAccessToken({ expirationTimeInMinutes: 5 });
40+
```
41+
* Configure a role that can join group `group1` directly when it connects using this Client Access URL
42+
```js
43+
let token = await serviceClient.getClientAccessToken({ roles: ["webpubsub.joinLeaveGroup.group1"] });
44+
```
45+
* Configure a role that the client can send messages to group `group1` directly when it connects using this Client Access URL
46+
```js
47+
let token = await serviceClient.getClientAccessToken({ roles: ["webpubsub.sendToGroup.group1"] });
48+
```
49+
* Configure a group `group1` that the client will join once it connects using this Client Access URL
50+
```js
51+
let token = await serviceClient.getClientAccessToken({ groups: ["group1"] });
52+
```
53+
54+
# [C#](#tab/csharp)
55+
56+
1. Follow [./reference-server-sdk-csharp#getting-started] to create a `WebPubSubServiceClient` object `service`
57+
58+
2. Generate Client Access URL by calling `WebPubSubServiceClient.GetClientAccessUri`:
59+
* Configure user ID
60+
```csharp
61+
var url = service.GetClientAccessUri(userId: "user1");
62+
```
63+
* Configure the lifetime of the token
64+
```csharp
65+
var url = service.GetClientAccessUri(expiresAfter: TimeSpan.FromMinutes(5));
66+
```
67+
* Configure a role that can join group `group1` directly when it connects using this Client Access URL
68+
```csharp
69+
var url = service.GetClientAccessUri(roles: new string[] { "webpubsub.joinLeaveGroup.group1" });
70+
```
71+
* Configure a role that the client can send messages to group `group1` directly when it connects using this Client Access URL
72+
```csharp
73+
var url = service.GetClientAccessUri(roles: new string[] { "webpubsub.sendToGroup.group1" });
74+
```
75+
* Configure a group `group1` that the client will join once it connects using this Client Access URL
76+
```csharp
77+
var url = service.GetClientAccessUri(groups: new string[] { "group1" });
78+
```
79+
80+
# [Python](#tab/python)
81+
82+
1. Follow [./reference-server-sdk-python.md#install-the-package] to create a `WebPubSubServiceClient` object `service`
83+
84+
2. Generate Client Access URL by calling `WebPubSubServiceClient.get_client_access_token`:
85+
* Configure user ID
86+
```python
87+
token = service.get_client_access_token(user_id="user1")
88+
```
89+
* Configure the lifetime of the token
90+
```python
91+
token = service.get_client_access_token(minutes_to_expire=5)
92+
```
93+
* Configure a role that can join group `group1` directly when it connects using this Client Access URL
94+
```python
95+
token = service.get_client_access_token(roles=["webpubsub.joinLeaveGroup.group1"])
96+
```
97+
* Configure a role that the client can send messages to group `group1` directly when it connects using this Client Access URL
98+
```python
99+
token = service.get_client_access_token(roles=["webpubsub.sendToGroup.group1"])
100+
```
101+
* Configure a group `group1` that the client will join once it connects using this Client Access URL
102+
```python
103+
token = service.get_client_access_token(groups=["group1"])
104+
```
105+
106+
# [Java](#tab/java)
107+
108+
1. Follow [./reference-server-sdk-java.md#getting-started] to create a `WebPubSubServiceClient` object `service`
109+
110+
2. Generate Client Access URL by calling `WebPubSubServiceClient.getClientAccessToken`:
111+
* Configure user ID
112+
```java
113+
GetClientAccessTokenOptions option = new GetClientAccessTokenOptions();
114+
option.setUserId(id);
115+
WebPubSubClientAccessToken token = service.getClientAccessToken(option);
116+
```
117+
* Configure the lifetime of the token
118+
```java
119+
GetClientAccessTokenOptions option = new GetClientAccessTokenOptions();
120+
option.setExpiresAfter(Duration.ofDays(1));
121+
WebPubSubClientAccessToken token = service.getClientAccessToken(option);
122+
```
123+
* Configure a role that can join group `group1` directly when it connects using this Client Access URL
124+
```java
125+
GetClientAccessTokenOptions option = new GetClientAccessTokenOptions();
126+
option.addRole("webpubsub.joinLeaveGroup.group1");
127+
WebPubSubClientAccessToken token = service.getClientAccessToken(option);
128+
```
129+
* Configure a role that the client can send messages to group `group1` directly when it connects using this Client Access URL
130+
```java
131+
GetClientAccessTokenOptions option = new GetClientAccessTokenOptions();
132+
option.addRole("webpubsub.sendToGroup.group1");
133+
WebPubSubClientAccessToken token = service.getClientAccessToken(option);
134+
```
135+
* Configure a group `group1` that the client will join once it connects using this Client Access URL
136+
```java
137+
GetClientAccessTokenOptions option = new GetClientAccessTokenOptions();
138+
option.setGroups(Arrays.asList("group1")),
139+
WebPubSubClientAccessToken token = service.getClientAccessToken(option);
140+
```
141+
---
142+
143+
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 leverage the general authentication/authorization workflow to validate the client request. Only valid client requests can get the Client Access URL back.
144+
145+
## Invoke the Generate Client Token REST API
146+
147+
You can enable Azure AD in your service and use the AAD token to invoke [Generate Client Token rest API](/rest/api/webpubsub/dataplane/web-pub-sub/generate-client-token) to get the token for the client to use.
148+
149+
1. Follow [Authorize from application](./howto-authorize-from-application.md) to enable Azure AD.
150+
2. Get the AAD token with Postman:
151+
1. For the URI, enter `https://login.microsoftonline.com/<TENANT ID>/oauth2/token`. Replace `<TENANT ID>` with the **Directory (tenant) ID value** in the **Overview** tab of the application you created earlier.
152+
2. On the **Headers** tab, add **Content-Type** key and `application/x-www-form-urlencoded` for the value.
153+
3. Switch to the **Body** tab, and add the following keys and values.
154+
1. Select `x-www-form-urlencoded`.
155+
2. Add `grant_type` key, and type `client_credentials` for the value.
156+
3. Add `client_id` key, and paste the value of **Application (client) ID** in the **Overview** tab of the application you created earlier.
157+
4. Add `client_secret` key, and paste the value of client secret you noted down earlier.
158+
5. Add `resource` key, and type `https://webpubsub.azure.com` for the value.
159+
4. Select **Send** to send the request to get the token. You see the AAD token in the `access_token` field.
160+
[![How to get Azure AD token using postman](.media/howto-generate-client-access-url/get-azure-ad-token-using-postman-response.png)]
161+
3. Use the AAD token to invoke `:generateToken` with Postman:
162+
1. For the URI, enter `https://{Endpoint}/api/hubs/{hub}/:generateToken?api-version=2022-11-01`
163+
2. On the **Auth** tab, select **Bearer Token** and paste the AAD token fetched in the previous step
164+
3. Select **Send** and you see the Client Access Token in the response:
165+
```json
166+
{
167+
"token": "ABCDEFG.ABC.ABC"
168+
}
169+
```
170+
4. The Client Access URI is in the format of `wss://<endpoint>/client/hubs/<hub_name>?access_token=<token>`
171+

‎articles/azure-web-pubsub/media/howto-generate-client-access-url/get-azure-ad-token-using-postman-response.png

119 KB
Loading

‎articles/azure-web-pubsub/toc.yml

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -49,19 +49,21 @@
4949
href: howto-websocket-connect.md
5050
- name: Create reliable Websocket clients
5151
href: howto-develop-reliable-clients.md
52+
- name: Generate Client Access URL
53+
href: howto-generate-client-access-url.md
5254
- name: Configure event handler
5355
href: howto-develop-eventhandler.md
5456
- name: Send client events to Event Hubs
5557
href: howto-develop-event-listener.md
56-
- name: Create `WebPubSubServiceClient` with Azure Identity
58+
- name: Use server SDK with Azure Identity
5759
items:
58-
- name: Create `WebPubSubServiceClient` with Azure Identity and .NET
60+
- name: Use server SDK with Azure Identity and .NET
5961
href: howto-create-serviceclient-with-net-and-azure-identity.md
60-
- name: Create `WebPubSubServiceClient` with Azure Identity and Java
62+
- name: Use server SDK with Azure Identity and Java
6163
href: howto-create-serviceclient-with-java-and-azure-identity.md
62-
- name: Create `WebPubSubServiceClient` with Azure Identity and JavaScript
64+
- name: Use server SDK with Azure Identity and JavaScript
6365
href: howto-create-serviceclient-with-javascript-and-azure-identity.md
64-
- name: Create `WebPubSubServiceClient` with Azure Identity and Python
66+
- name: Use server SDK with Azure Identity and Python
6567
href: howto-create-serviceclient-with-python-and-azure-identity.md
6668
- name: Monitor
6769
items:

0 commit comments

Comments
 (0)