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.1</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
Use the createUser function to create a new user from CommunicationIdentityClient
Use the getRelayConfiguration function to get a Relay Configuration
CommunicationIdentityClient communicationIdentityClient = new CommunicationIdentityClientBuilder()
.connectionString(connectionString)
.buildClient();
CommunicationUserIdentifier user = communicationIdentityClient.createUser();
System.out.println("User id: " + user.getId());
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());
}
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 (CommunicationErrorResponseException ex) {
System.out.println(ex.getMessage());
}
Refer to the offical 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.
