Custom Domain Names with BizTalk Services


Each BizTalk Services deployment gets a unique URL like 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 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 instead of URLs. The certificate in this case can either be for a generic sub-domain * or for 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
  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
  4. The application also queries the DNS to determine the IP of the deployment
  5. Azure DNS has a CNAME for mapping it to The client would get the URL
  6. Azure DNS also has A record to map the 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 to Customers can use for all operations on the corresponding url. Adding this entry is specific to the DNS server (see example later): IN CNAME

It is assumed that is already owned by the user.


Incase of HTTPS the client/browser will lookup the address and also the certificate of The certificate should be available in since the HTTPS session is established with the latter and the browser requests are being serviced using 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. IN A 

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 or generic *
  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 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 to

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 domain
  2. Client application first gets the token from ACS for
  3. ACS will have the relying party information to return token for not
  4. Client application also queries the Customer DNS, which responds back with
  5. Client then queries the Azure DNS for and gets back
  6. Client again queries the Azure DNS for and determines the IP as
  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





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. 


  • 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.



Comments (0)