Custom Domain Names with BizTalk Services

  • Article

Background

Each BizTalk Services deployment gets a unique URL like https://contoso.biztalk.windows.net where <contoso> is a globally unique name input by the user. The https session traffic for this deployment will be encrypted using a SSL .pfx certificate. Since the biztalk.windows.net URLs are HTTPS based either a self-signed certificate or a certificate issued by a Certificate Authority is required. Few customers prefer to use their existing domain-friendly URLs like app.contoso.com instead of biztalk.windows.net URLs. The certificate in this case can either be for a generic sub-domain *.contoso.com or for app.contoso.com. All certificates are uploaded to the BizTalk Services deployment during service creation and the Common Name (CN) in the certificate will be validated against the custom domain URL.

Default Domain

The BizTalk Service deployment with the default domain works as follows:

  1. Customer creates BizTalk Services deployment and uploads self-signed certificate for contoso.biztalk.windows.net.
  2. When a application wants to connect with a bridge/agreement endpoint, its first gets the token from ACS
  3. ACS will have the relying party information to return token for contoso.biztalk.windows.net
  4. The application also queries the DNS to determine the IP of the deployment
  5. Azure DNS has a CNAME for contoso.biztalk.windows.net mapping it to contosoXXX.cloudapp.net. The client would get the cloudapp.net URL
  6. Azure DNS also has A record to map the cloudapp.net name to the IP address (VIP) where the service is hosted. The client would get the IP of the deployment
  7. Client application connect to the service at the IP along with the ACS Token
  8. Steps 1-6 are the same if BizTalk Portal queries for data similar to the client application

 

DNS Records

You can use a CNAME record or an A record in DNS to configure custom domains. Both operations require access to the domain’s DNS controller. Any changes to the records requires the changes to be propagated across all servers.

CNAME record

A CNAME is a canonical name aliasing one domain name for another. For example, you can map app.contoso.com to contoso.biztalk.windows.net. Customers can use app.conotos.com for all operations on the corresponding biztalk.net url. Adding this entry is specific to the DNS server (see example later):

app.contoso.com IN CNAME contoso.biztalk.windows.net

It is assumed that contoso.com is already owned by the user.

CNAME with HTTPS

Incase of HTTPS the client/browser will lookup the address and also the certificate of app.contoso.com. The certificate should be available in contoso.biztalk.windows.net since the HTTPS session is established with the latter and the browser requests are being serviced using app.contoso.com URL. For example, if there is a mismatch with the certificate names, the browser would indicate a warning in the address bar.  

A or AAAA record

A record is the address record that maps a DNS domain or a subdomain to its IP Address. While A record is for IP4 addresses, AAAA record is used for IPv6 addresses.

contoso.biztalk.windows.net IN A 1.2.3.4 

Custom Domain with BizTalk Services

There are 3 key steps to getting custom domain working correctly – create the domain name and its SSL certificate, use the certificate and name while deploying BizTalk Services and finally mapping the DNS entries so all calls get routed correctly.

Create Custom Domain and its SSL certificate

  1. You need to register a domain name and create a corresponding SSL certificate as part of the process or using your existing domain name and SSL certificate. If you are purchasing a certificate, it can be for a specific sub-domain like app.contoso.com or generic *.contoso.com
  2. If the SSL certificate is a .pem certificate, you would need to convert it into a .pfx certificate (this is the same as pkcs12 version)

Configure BizTalk Services

  1. Create BizTalk Services deployment with app.contoso.com as custom domain name

   2. Upload the .pfx certificate in the BizTalk Services creation wizard

Configure DNS

  1. Log into to you DNS server to manage your DNS entries.
  2. Add a CNAME record mapping app.contoso.info to contoso.biztalk.windows.net

How this works

The BizTalk Service deployment with custom domain works as follows:

  1. When a client application wants to connect with a bridge/agreement endpoint, its addresses app.contoso.com domain
  2. Client application first gets the token from ACS for app.contoso.com
  3. ACS will have the relying party information to return token for app.contoso.com not contoso.biztalk.windows.net
  4. Client application also queries the Customer DNS, which responds back with contoso.biztalk.windows.net
  5. Client then queries the Azure DNS for contoso.biztalk.windows.net and gets back contosoXXX.cloudapp.net
  6. Client again queries the Azure DNS for contosoXXX.cloudapp.net and determines the IP as 1.2.3.4
  7. Client connects to this IP address and passes the ACS token
  8. Steps 2-7 are the same if BizTalk Portal queries for data similar to client application

 

 

 

Verification

After custom domain has been successfully configured you can check the settings in the following places:

  1. From the Azure portal, check Service URL in the dashboard quick glance information
  2. For EAI, the bridge configuration surface in Visual Studio should be set to the domain URL after installing the relevant client certificate.
  3. The Output window would indicate the custom domain bridge URL during deployment
  4. For EDI, all deployed agreements will have the domain URL as part of the inbound URL in send side and transport of the receive side in X12 and AS2 agreements. 

FAQ

  • Can I use more than one custom domain name per BizTalk Services deployment?

No, currently we support only one domain certificate with a single name for each deployment

  • How do I use certificates with extensions other than .pfx?

You would have to convert certificates with extensions like .pem, .p7b to .pfx. There are tools available to have this conversion as long as the private key of the certificate is available

  • How do update an expired certificate of a domain name?

From the Azure portal, navigate to the dashboard page and you have an option to update the domain certificate of your BizTalk Services deployment

  • Can I change the domain name for a deployment after the BizTalk Service has been created?

In v1, the domain name with its certificate cannot be changed after the BizTalk Services deployment has been created.

References