Azure Communication Network Traversal Package client library for Java
Azure Communication Network Traversal is managing TURN credentials for Azure Communication Services.
It will provide TURN credentials to a user.
Source code | API reference documentation
Getting started
Prerequisites
- An Azure subscription. Create an account for free.
- Java Development Kit (JDK) version 8 or above.
- Apache Maven.
- A Communication Services resource. You can use the Azure Portal or the Azure PowerShell to set it up.
Include the package
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-communication-networktraversal</artifactId>
<version>1.0.0-beta.3</version>
</dependency>
Authenticate the client
There are two forms of authentication to use the Relay SDK:
Azure Active Directory Token Authentication
A DefaultAzureCredential
object can be passed to the CommunicationRelayClientBuilder
via the credential() function. Endpoint must also be set via the endpoint() function.
AZURE_CLIENT_SECRET
, AZURE_CLIENT_ID
and AZURE_TENANT_ID
environment variables
are needed to create a DefaultAzureCredential object.
// You can find your endpoint and access key from your resource in the Azure Portal
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";
CommunicationRelayClient communicationRelayClient = new CommunicationRelayClientBuilder()
.endpoint(endpoint)
.credential(new DefaultAzureCredentialBuilder().build())
.buildClient();
AzureKeyCredential Authentication
Network Traversal uses HMAC authentication with the resource access key.
The access key can be used to create an AzureKeyCredential and provided to the CommunicationRelayClientBuilder
via the credential() function. Endpoint must also be set via the endpoint() function.
// You can find your endpoint and access key from your resource in the Azure Portal
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";
AzureKeyCredential keyCredential = new AzureKeyCredential("<access-key>");
CommunicationRelayClient communicationRelayClient = new CommunicationRelayClientBuilder()
.endpoint(endpoint)
.credential(keyCredential)
.buildClient();
Connection String Authentication
Alternatively, you can provide the entire connection string using the connectionString() function instead of providing the endpoint and access key.
// You can find your connection string from your resource in the Azure Portal
String connectionString = "<connection_string>";
CommunicationRelayClient communicationRelayClient = new CommunicationRelayClientBuilder()
.connectionString(connectionString)
.buildClient();
Key concepts
CommunicationRelayClient
and CommunicationRelayAsyncClient
provide the functionalities to manage users and user tokens.
Examples
Getting a new Relay Configuration
CommunicationRelayClient communicationRelayClient = createCommunicationNetworkTraversalClient();
CommunicationRelayConfiguration config = communicationRelayClient.getRelayConfiguration();
System.out.println("Expires on:" + config.getExpiresOn());
List<CommunicationIceServer> iceServers = config.getIceServers();
for (CommunicationIceServer iceS : iceServers) {
System.out.println("URLS: " + iceS.getUrls());
System.out.println("Username: " + iceS.getUsername());
System.out.println("Credential: " + iceS.getCredential());
System.out.println("RouteType: " + iceS.getRouteType());
}
Getting a new Relay Configuration providing a user
Use the createUser
function to create a new user from CommunicationIdentityClient
Use the getRelayConfiguration
function to get a Relay Configuration
CommunicationIdentityClient communicationIdentityClient = createCommunicationIdentityClient();
CommunicationUserIdentifier user = communicationIdentityClient.createUser();
System.out.println("User id: " + user.getId());
CommunicationRelayClient communicationRelayClient = createCommunicationNetworkTraversalClient();
CommunicationRelayConfiguration config = communicationRelayClient.getRelayConfiguration(user);
System.out.println("Expires on:" + config.getExpiresOn());
List<CommunicationIceServer> iceServers = config.getIceServers();
for (CommunicationIceServer iceS : iceServers) {
System.out.println("URLS: " + iceS.getUrls());
System.out.println("Username: " + iceS.getUsername());
System.out.println("Credential: " + iceS.getCredential());
System.out.println("RouteType: " + iceS.getRouteType());
}
Getting a new Relay Configuration providing a Route Type
CommunicationRelayClient communicationRelayClient = createCommunicationNetworkTraversalClient();
CommunicationRelayConfiguration config = communicationRelayClient.getRelayConfiguration(RouteType.ANY);
System.out.println("Expires on:" + config.getExpiresOn());
List<CommunicationIceServer> iceServers = config.getIceServers();
for (CommunicationIceServer iceS : iceServers) {
System.out.println("URLS: " + iceS.getUrls());
System.out.println("Username: " + iceS.getUsername());
System.out.println("Credential: " + iceS.getCredential());
System.out.println("RouteType: " + iceS.getRouteType());
}
Troubleshooting
All user token service operations will throw an exception on failure.
try {
CommunicationUserIdentifier user = communicationIdentityClient.createUser();
CommunicationRelayClient communicationRelayClient = createCommunicationNetworkTraversalClient();
CommunicationRelayConfiguration config = communicationRelayClient.getRelayConfiguration(user);
} catch (RuntimeException ex) {
System.out.println(ex.getMessage());
}
Refer to the official documentation for more details and error codes (to be added).
Next steps
Please take a look at the [samples][samples] directory for detailed examples of how to use this library to manage relay configuration
Contributing
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution.
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
Package | Description |
---|---|
com.azure.communication.networktraversal |
Package containing the classes for AzureCommunicationNetworkTraversal.
|
com.azure.communication.networktraversal.models |
Package containing classes for CommunicationNetworkingClient.
|