Skip to content

Commit a3512f8

Browse files
laurabrenlaurabren
authored
Merge pull request #173806 from rahulva-msft/relay_docs_2
Network traversal document updates
2 parents 644e995 + 495c1e4 commit a3512f8

File tree

7 files changed

+344
-15
lines changed

7 files changed

+344
-15
lines changed

‎articles/communication-services/concepts/network-traversal.md

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
title: Conceptual documentation for Azure Communication Services - Network Traversal
3+
titleSuffix: An Azure Communication Services Concept Document
4+
description: Learn more about Azure Communication Services Network Traversal SDKs and REST APIs.
5+
author: rahulva
6+
manager: shahen
7+
services: azure-communication-services
8+
ms.author: rahulva
9+
ms.date: 09/20/2021
10+
ms.topic: conceptual
11+
ms.service: azure-communication-services
12+
---
13+
14+
# Network Traversal Concepts
15+
16+
Real-time Relays solve the problem of NAT (Network Address Translation) traversal for Peer-to-Peer (P2P) connections. Most devices on the internet today have an IP address used for internal LAN traffic (home or corporate network) or an externally visible address (router or NAT gateway). To connect two devices on the internet, the external address is required, but is typically not available to a device behind a NAT gateway. To address the connectivity issue, following protocols are used:
17+
18+
STUN (Session Traversal Utilities for NAT) offers a protocol to allow devices to exchange external IPs on the internet. If the clients can see each other, there is typically no need for a relay through a TURN service since the connection can be made peer-to-peer. A STUN server's job is to respond to request for a device's external IP.
19+
20+
TURN (Traversal Using Relays around NAT) is an extension of the STUN protocol that also relays the data between two endpoints through a mutually visible server.
21+
22+
## ACS Network Traversal Overview
23+
24+
WebRTC(Web Real-Time Technologies) allow web browsers to stream audio, video, and data between devices without needing to have a gateway in the middle. Some of the common use cases here are voice, video, broadcasting, and screen sharing. To connect two endpoints on the internet, their external IP address is required. External IP is typically not available for devices sitting behind a corporate firewall. The protocols like STUN (Session Traversal Utilities for NAT) and TURN (Traversal Using Relays around NAT) are used to help the endpoints communicate.
25+
26+
Azure Communication Service provides high bandwidth, low latency connections between peers for real-time communications scenarios. The ACS Network Traversal Service hosts TURN servers for use with the NAT scenarios. Azure Real-Time Relay Service exposes the existing STUN/TURN infrastructure as a Platform as a Service(PaaS) Azure offering. The service will provide low-level STUN and TURN services. Users are then billed proportional to the amount of data relayed.
27+
28+
29+
## Next Steps:
30+
31+
* For an introduction to authentication, see [Authenticate to Azure Communication Services](./authentication.md).
32+
* For an introduction to acquire relay candidates, see [Create and manage access tokens](../quickstarts/relay-token.md).

‎articles/communication-services/quickstarts/includes/relay-token-java.md

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
---
2+
title: include file
3+
description: include file
4+
services: azure-communication-services
5+
author: rahulva
6+
manager: shahen
7+
ms.service: azure-communication-services
8+
ms.subservice: azure-communication-services
9+
ms.date: 09/20/2021
10+
ms.topic: include
11+
ms.custom: include file
12+
ms.author: rahulva
13+
---
14+
15+
> [!NOTE]
16+
> Find the finalized code for this quickstart on [GitHub](https://github.com/Azure-Samples/communication-services-java-quickstarts/tree/main/relay-token-quickstart)
17+
18+
## Prerequisites for Java
19+
20+
- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
21+
- [Java Development Kit (JDK)](/azure/developer/java/fundamentals/java-jdk-install) version 8 or above.
22+
- [Apache Maven](https://maven.apache.org/download.cgi).
23+
- A deployed Communication Services resource and connection string. [Create a Communication Services resource](../create-communication-resource.md).
24+
25+
## Setting Up
26+
27+
### Create a new Java application
28+
29+
Open your terminal or command window. Navigate to the directory where you'd like to create your Java application. Run the command below to generate the Java project from the maven-archetype-quickstart template.
30+
31+
```console
32+
mvn archetype:generate -DgroupId=com.communication.quickstart -DartifactId=communication-quickstart -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false
33+
```
34+
35+
You'll notice that the 'generate' task created a directory with the same name as the `artifactId`. Under this directory, the src/main/java directory contains the project source code, the `src/test/java directory` contains the test source, and the `pom.xml` file is the project's Project Object Model, or POM.
36+
37+
### Install the package
38+
39+
Open the **pom.xml** file in your text editor. Add the following dependency element to the group of dependencies.
40+
41+
```xml
42+
<dependency>
43+
<groupId>com.azure</groupId>
44+
<artifactId>azure-communication-identity</artifactId>
45+
<version>1.0.0</version>
46+
</dependency>
47+
```
48+
49+
### Set up the app framework
50+
51+
From the project directory:
52+
53+
1. Navigate to the `/src/main/java/com/communication/quickstart` directory
54+
2. Open the `App.java` file in your editor
55+
3. Replace the `System.out.println("Hello world!");` statement
56+
4. Add `import` directives
57+
58+
Use the following code to begin:
59+
60+
```java
61+
package com.communication.quickstart;
62+
63+
import com.azure.communication.common.*;
64+
import com.azure.communication.identity.*;
65+
import com.azure.communication.identity.models.*;
66+
import com.azure.core.credential.*;
67+
import com.communication.network.traversal.*;
68+
69+
import java.io.IOException;
70+
import java.time.*;
71+
import java.util.*;
72+
73+
public class App
74+
{
75+
public static void main( String[] args ) throws IOException
76+
{
77+
System.out.println("Azure Communication Services - Network Credentials Quickstart");
78+
// Quickstart code goes here
79+
}
80+
}
81+
```
82+
83+
## Authenticate the client
84+
85+
Instantiate a `CommunicationIdentityClient` with your resource's access key and endpoint. Learn how to [manage your resource's connection string](../create-communication-resource.md#store-your-connection-string). In addition, you can initialize the client with any custom HTTP client the implements the `com.azure.core.http.HttpClient` interface.
86+
87+
Add the following code to the `main` method:
88+
89+
```java
90+
// Your can find your endpoint and access key from your resource in the Azure portal
91+
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";
92+
String accessKey = "SECRET";
93+
94+
CommunicationRelayClient communicationRelayClient = new CommunicationRelayClientBuilder()
95+
.endpoint(endpoint)
96+
.credential(new DefaultAzureCredentialBuilder().build())
97+
.buildClient();
98+
99+
```
100+
101+
You can also provide the entire connection string using the `connectionString()` function instead of providing the endpoint and access key.
102+
```java
103+
// Your can find your connection string from your resource in the Azure portal
104+
String connectionString = "<connection_string>";
105+
106+
CommunicationRelayClient communicationRelayClient = new CommunicationRelayClientBuilder()
107+
.connectionString(connectionString)
108+
.buildClient();
109+
```
110+
111+
## Create an identity
112+
113+
Azure Communication Services maintains a lightweight identity directory. Use the `createUser` method to create a new entry in the directory with a unique `Id`. Store received identity with mapping to your application's users. For example, by storing them in your application server's database. The identity is required later to issue access tokens.
114+
115+
```java
116+
CommunicationUserIdentifier user = communicationIdentityClient.createUser();
117+
System.out.println("\nCreated an identity with ID: " + user.getId());
118+
```
119+
120+
## Getting the relay configuration
121+
Call the Azure Communication token service to exchange the user access token for a TURN service token
122+
123+
```java
124+
CommunicationIdentityClient communicationIdentityClient = new CommunicationIdentityClientBuilder()
125+
.connectionString(connectionString)
126+
.buildClient();
127+
128+
CommunicationUserIdentifier user = communicationIdentityClient.createUser();
129+
System.out.println("User id: " + user.getId());
130+
131+
CommunicationRelayConfiguration config = communicationRelayClient.getRelayConfiguration(user);
132+
133+
System.out.println("Expires on:" + config.getExpiresOn());
134+
List<CommunicationIceServer> iceServers = config.getIceServers();
135+
136+
for (CommunicationIceServer iceS : iceServers) {
137+
System.out.println("URLS: " + iceS.getUrls());
138+
System.out.println("Username: " + iceS.getUsername());
139+
System.out.println("Credential: " + iceS.getCredential());
140+
}
141+
```
142+
143+
## Run the code
144+
145+
Navigate to the directory containing the *pom.xml* file and compile the project by using the following `mvn` command.
146+
147+
```console
148+
mvn compile
149+
```
150+
151+
Then, build the package.
152+
153+
```console
154+
mvn package
155+
```
156+
157+
Run the following `mvn` command to execute the app.
158+
159+
Navigate to the directory containing the *pom.xml* file and compile the project by using the following `mvn` command.
160+
161+
```console
162+
mvn compile
163+
```
164+
165+
Then, build the package.
166+
167+
```console
168+
mvn package
169+
```
170+
171+
Run the following `mvn` command to execute the app.
172+
173+
```console
174+
mvn exec:java -Dexec.mainClass="com.communication.quickstart.App" -Dexec.cleanupDaemonThreads=false
175+
```

‎articles/communication-services/quickstarts/includes/relay-token-net.md

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ ms.author: shahen
2626
dotnet new console -o RelayTokenQuickstart
2727
```
2828

29-
1. Change your directory to the newly created app folder and use the `dotnet build` command to compile your application.
29+
2. Change your directory to the newly created app folder and use the `dotnet build` command to compile your application.
3030

3131
```console
3232
cd RelayTokenQuickstart
@@ -91,7 +91,7 @@ var client = new CommunicationIdentityClient(connectionString);
9191
Azure Communication Services maintains a lightweight identity directory. Use the `createUser` method to create a new entry in the directory with a unique `Id`. Store received identity with mapping to your application's users. For example, by storing them in your application server's database. The identity is required later to issue access tokens.
9292

9393
```csharp
94-
var identityResponse = await client.CreateUserAsync();
94+
var identityResponse = await client.CreateUserAsync().Result;
9595
var identity = identityResponse.Value;
9696
Console.WriteLine($"\nCreated an identity with ID: {identity.Id}");
9797
```
@@ -103,18 +103,18 @@ Call the Azure Communication token service to exchange the user access token for
103103
```csharp
104104
var relayClient = new CommunicationRelayClient("COMMUNICATION_SERVICES_CONNECTION_STRING");
105105

106-
Response<CommunicationRelayConfiguration> turnTokenResponse = await relayClient.GetRelayConfigurationAsync(identity);
106+
Response<CommunicationRelayConfiguration> turnTokenResponse = await relayClient.GetRelayConfigurationAsync(identity).Result;
107107
DateTimeOffset turnTokenExpiresOn = turnTokenResponse.Value.ExpiresOn;
108-
IReadOnlyList<CommunicationTurnServer> turnServers = turnTokenResponse.Value.TurnServers;
108+
IReadOnlyList<CommunicationIceServer> iceServers = turnTokenResponse.Value.IceServers;
109109
Console.WriteLine($"Expires On: {turnTokenExpiresOn}");
110-
foreach (CommunicationTurnServer turnServer in turnServers)
110+
foreach (CommunicationIceServer iceServer in iceServers)
111111
{
112-
foreach (string url in turnServer.Urls)
112+
foreach (string url in iceServer.Urls)
113113
{
114114
Console.WriteLine($"TURN Url: {url}");
115115
}
116-
Console.WriteLine($"TURN Username: {turnServer.Username}");
117-
Console.WriteLine($"TURN Credential: {turnServer.Credential}");
116+
Console.WriteLine($"TURN Username: {iceServer.Username}");
117+
Console.WriteLine($"TURN Credential: {iceServer.Credential}");
118118
}
119119
```
120120

‎articles/communication-services/quickstarts/includes/relay-token-python.md

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
---
2+
title: include file
3+
description: include file
4+
services: azure-communication-services
5+
author: rahulva
6+
manager: shahen
7+
ms.service: azure-communication-services
8+
ms.subservice: azure-communication-services
9+
ms.date: 07/30/2021
10+
ms.topic: include
11+
ms.custom: include file
12+
ms.author: rahulva
13+
---
14+
15+
> [!NOTE]
16+
> Find the finalized code for this quickstart on [GitHub](https://github.com/Azure-Samples/communication-services-python-quickstarts/tree/main/relay-token-quickstart)
17+
18+
## Prerequisites for Python
19+
20+
An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
21+
- [Python](https://www.python.org/downloads/) 2.7 or 3.6+.
22+
- An active Communication Services resource and connection string. [Create a Communication Services resource](../create-communication-resource.md).
23+
24+
## Setting Up
25+
26+
### Create a new Python application
27+
28+
1. Open your terminal or command window create a new directory for your app, and navigate to it.
29+
30+
```console
31+
mkdir access-tokens-quickstart && cd relay-tokens-quickstart
32+
```
33+
34+
2. Use a text editor to create a file called **issue-relay-tokens.py** in the project root directory and add the structure for the program, including basic exception handling. You'll add all the source code for this quickstart to this file in the following sections.
35+
36+
```python
37+
import os
38+
from azure.communication.networktraversal import CommunicationRelayClient
39+
from azure.identity import DefaultAzureCredential
40+
from azure.communication.identity import CommunicationIdentityClient
41+
42+
try:
43+
print("Azure Communication Services - Access Relay Configuration Quickstart")
44+
# Quickstart code goes here
45+
except Exception as ex:
46+
print("Exception:")
47+
print(ex)
48+
```
49+
50+
### Install the package
51+
52+
While still in the application directory, install the Azure Communication Services Identity SDK for Python package by using the `pip install` command.
53+
54+
```console
55+
pip install azure-communication-identity
56+
pip install azure.communication.networktraversal
57+
```
58+
59+
## Authenticate the client
60+
61+
Instantiate a `CommunicationIdentityClient` with your resource's access key and endpoint. The code below retrieves the connection string for the resource from an environment variable named `COMMUNICATION_SERVICES_CONNECTION_STRING`. Learn how to [manage your resource's connection string](../create-communication-resource.md#store-your-connection-string).
62+
63+
Add this code inside the `try` block:
64+
65+
```python
66+
67+
# You can find your endpoint and access token from your resource in the Azure Portal
68+
connection_str = "endpoint=ENDPOINT;accessKey=KEY"
69+
endpoint = "https://<RESOURCE_NAME>.communication.azure.com"
70+
71+
# To use Azure Active Directory Authentication (DefaultAzureCredential) make sure to have
72+
# AZURE_TENANT_ID, AZURE_CLIENT_ID and AZURE_CLIENT_SECRET as env variables.
73+
# We also need Identity client to get a User Identifier
74+
identity_client = CommunicationIdentityClient(endpoint, DefaultAzureCredential())
75+
relay_client = CommunicationRelayClient(endpoint, DefaultAzureCredential())
76+
77+
#You can also authenticate using your connection string
78+
identity_client = CommunicationIdentityClient.from_connection_string(self.connection_string)
79+
relay_client = CommunicationRelayClient.from_connection_string(self.connection_string)
80+
```
81+
82+
## Create a user from identity
83+
84+
Azure Communication Services maintains a lightweight identity directory. Use the `create_user` method to create a new entry in the directory with a unique `Id`. Store received identity with mapping to your application's users. For example, by storing them in your application server's database. The identity is required later to issue access tokens.
85+
86+
```python
87+
user = identity_client.create_user()
88+
```
89+
90+
## Getting the relay configuration
91+
Call the Azure Communication token service to exchange the user access token for a TURN service token
92+
93+
```python
94+
relay_configuration = relay_client.get_relay_configuration(user)
95+
96+
for iceServer in config.ice_servers:
97+
assert iceServer.username is not None
98+
print('Username: ' + iceServer.username)
99+
100+
assert iceServer.credential is not None
101+
print('Credential: ' + iceServer.credential)
102+
103+
assert iceServer.urls is not None
104+
for url in iceServer.urls:
105+
print('Url:' + url)
106+
```
107+
108+
## Run the code
109+
110+
From a console prompt, navigate to the directory containing the *issue-relay-tokens.py* file, then execute the following `python` command to run the app.
111+
112+
```console
113+
python ./issue-relay-tokens.py
114+
```

0 commit comments

Comments
 (0)