Edit

Configure a test customer for Microsoft Teams Direct Routing with Azure Communications Gateway

  • Article

Testing Microsoft Teams Direct Routing requires some test numbers in a Microsoft 365 tenant, as if you're providing service to a real customer. We call this tenant (which you control) a test customer tenant, corresponding to your test customer (to which you allocate the test numbers). Setting up a test customer requires configuration in the test customer tenant and on Azure Communications Gateway. This article explains how to set up that configuration. You can then configure test users and numbers in the tenant and start testing.

Tip

When you onboard a real customer, you'll typically need to ask them to change their tenant's configuration, because your organization won't have permission. You'll still need to make configuration changes on Azure Communications Gateway.

For more information about how Azure Communications Gateway and Microsoft Teams use tenant configuration to route calls, see Support for multiple customers with the Microsoft Teams multitenant model.

This article provides detailed guidance equivalent to the following steps in the Microsoft Teams documentation for configuring an SBC for multiple tenants.

  • Registering a subdomain name in the customer tenant.
  • Configuring derived trunks in the customer tenant (including failover).

Prerequisites

You must have a Microsoft 365 tenant that you can use as a test customer. You must have at least one number that you can allocate to this test customer.

You must complete the following procedures.

You must provision Azure Communications Gateway with the details of your test customer tenant during this procedure.

  • To use Azure Communications Gateway's Number Management Portal (preview) for provisioning (recommended), you must have Reader access to the Azure Communications Gateway resource and ProvisioningAPI.ReadUser and ProvisioningAPI.WriteUser roles for the AzureCommunicationsGateway enterprise application.
  • To use Azure Communications Gateway's Provisioning API (preview), you must be able to make requests using a client integrated with the API. You must also have access to the API Reference.

You must be able to sign in to the Microsoft 365 admin center for your test customer tenant as a Global Administrator.

You must be able to configure the tenant with at least two user or resource accounts licensed for Microsoft Teams. For more information on suitable licenses, see the Microsoft Teams documentation.

  • You need two user or resource accounts to activate the Azure Communications Gateway domains that you add to Microsoft 365 by following this article. Lab deployments require one account.
  • You need at least one user account to use for testing later when you carry out Configure test numbers for Microsoft Teams Direct Routing with Azure Communications Gateway. You can reuse one of the accounts that you use to activate the domains, or you can use an account with one of the other domain names for this tenant.

Choose a DNS subdomain label to use to identify the customer

Azure Communications Gateway has per-region domain names for connecting to Microsoft Teams Direct Routing. You need to set up subdomains of these domain names for your test customer. Microsoft Phone System and Azure Communications Gateway use these subdomains to match calls to tenants.

  1. Work out the per-region domain names for connecting to Microsoft Teams Direct Routing. These use the form 1-r<region-number>.<base-domain-name>. The base domain name is the Domain on your Azure Communications Gateway resource in the Azure portal.
  2. Choose a DNS label to identify the test customer.
    • The label must be up to eight characters in length and can only contain letters, numbers, underscores, and dashes.
    • You must not use wildcard subdomains or subdomains with multiple labels.
    • For example, you could allocate the label test.

    Important

    The full customer subdomains (including the per-region domain names) must be a maximum of 48 characters. Microsoft Entra ID does not support domain names of more than 48 characters. For example, the customer subdomain contoso1.1-r1.a1b2c3d4e5f6g7h8.commsgw.azure.com is 48 characters.

  3. Use this label to create a customer subdomain of each per-region domain name for your Azure Communications Gateway.
  4. Make a note of the label you choose and the corresponding customer subdomains.

For example:

  • Your base domain name might be <deployment-id>.commsgw.azure.com, where <deployment-id> is autogenerated and unique to the deployment.
  • Your per-region domain names are therefore:
    • 1-r1.<deployment-id>.commsgw.azure.com
    • 1-r2.<deployment-id>.commsgw.azure.com
  • If you allocate the label test, this label combined with the per-region domain names creates the following customer subdomains for your test customer:
    • test.1-r1.<deployment-id>.commsgw.azure.com
    • test.1-r2.<deployment-id>.commsgw.azure.com

Important

The per-region domain names for connecting to Microsoft Teams Direct Routing are different to the per-region domain names for connecting to your network.

Tip

Lab deployments have one per-region domain name. Your test customer therefore also only has one customer subdomain.

Start registering the subdomains in the customer tenant and get DNS TXT values

To route calls to a customer tenant, the customer tenant must be configured with the customer subdomains that you allocated in Choose a DNS subdomain label to use to identify the customer. Microsoft 365 then requires you (as the carrier) to create DNS records that use a verification code from the customer tenant.

  1. Sign into the Microsoft 365 admin center for the customer tenant as a Global Administrator.
  2. Using Add a subdomain to the customer tenant and verify it:
    1. Register the first customer subdomain (for example test.1-r1.<deployment-id>.commsgw.azure.com).
    2. Start the verification process using TXT records.
    3. Note the TXT value that Microsoft 365 provides.
  3. (Production deployments only) Repeat the previous step for the second customer subdomain.

Important

Don't complete the verification process yet. You must carry out Configure the customer on Azure Communications Gateway and generate DNS records first.

Configure the customer on Azure Communications Gateway and generate DNS records

Azure Communications Gateway includes a DNS server. You must use Azure Communications Gateway to create the DNS records required to verify the customer subdomains. To generate the records, provision the details of the customer tenant and the DNS TXT values on Azure Communications Gateway.

You can use Azure Communications Gateway's Number Management Portal (preview) or Provisioning API (preview).

  1. From the overview page for your Communications Gateway resource, find the Number Management section in the sidebar.
  2. Select Accounts.
  3. Select Create account.
  4. Enter an Account name and select the Enable Teams Direct Routing checkbox.
  5. Set Teams tenant ID to the ID of your test customer tenant.
  6. Optionally, select Enable call screening. This screening ensures that customers can only place Direct Routing calls from numbers that you have assigned to them.
  7. Set Subdomain to the label for the subdomain that you chose in Choose a DNS subdomain label to use to identify the customer (for example, test).
  8. Set the Subdomain token region fields to the TXT values that you obtained in Start registering the subdomains in the customer tenant and get DNS TXT values.
  9. Select Create.
  10. Confirm that the DNS records have been generated.
    1. On the Accounts pane, select the account name in the list.
    2. Confirm that Subdomain Provisioned State is Provisioned.

Finish verifying the domains in the customer tenant

When you have used Azure Communications Gateway to generate the DNS records for the customer subdomains, verify the subdomains in the Microsoft 365 admin center for your customer tenant.

  1. Sign into the Microsoft 365 admin center for the customer tenant as a Global Administrator.
  2. Select Settings > Domains.
  3. Finish verifying the customer subdomains by following Add a subdomain to the customer tenant and verify it.

Activate the domains in the customer tenant

To activate the customer subdomains in Microsoft 365, set up at least one user or resource account licensed for Microsoft Teams for each domain name. For information on the licenses you can use and instructions, see Activate the subdomain name.

Important

Ensure the accounts use the customer subdomains (for example, test.1-r1.<deployment-id>.commsgw.azure.com), instead of any existing domain names in the tenant.

Configure the customer tenant's call routing to use Azure Communications Gateway

In the customer tenant, configure a call routing policy (also called a voice routing policy) with a voice route that routes calls to Azure Communications Gateway.

Important

You must use PowerShell to set the PSTN gateways for the voice route, because the Microsoft Teams Admin Center doesn't support adding derived trunks. You can use the Microsoft Teams Admin Center for all other voice route configuration.

To set the PSTN gateways for a voice route, use the following PowerShell command.

Set-CsOnlineVoiceRoute -id "<voice-route-id>" -OnlinePstnGatewayList <customer-subdomain-1>, <customer-subdomain-2>

Next step

Configure test numbers