Domain and certificate bindings for IDN hostnames in Azure App Service
Published Jan 07 2024 09:28 PM 2,041 Views


When it comes to website security, one important step is to add a custom domain and connect it with a TLS/SSL certificate. This not only enhances the trust and safety of your website but also ensures that your visitors' information is encrypted and protected. Azure App Service provides TLS bindings for the most common custom domains. This blog discusses the special domain and certificate binding situations in Azure App Service for IDN hostnames.

What is an IDN hostname?

An IDN hostname is a domain name that includes characters used in the local representation of languages not written with the basic Latin alphabet "a-z". These characters can be Arabic, Hebrew, Chinese, Cyrillic, Tamil, Hindi, and more.
The internet is primarily based on ASCII, which does not support these characters. To overcome this limitation, IDNs are encoded using Punycode, allowing non-Latin character domain names to be used in the DNS.
When registering an IDN, you typically enter the domain in your language's script, and the domain registrar converts it into Punycode for DNS compatibility. Most modern web browsers display the IDN in its native script in the address bar for better readability, but they perform the DNS lookup using the Punycode representation.

What is Punnycode?

Punycode is a method used to represent domain names with non-ASCII characters in the ASCII format. Since domain names are typically written using ASCII characters, Punycode encoding allows non-Latin characters (like é or 漢字) to be converted into a compatible format. For example, the domain "résumé.com" is encoded as "" using Punycode. This ensures that domain names with non-ASCII characters can be registered and accessed in a standardized way across different systems and browsers. Punycode plays a crucial role in enabling a more inclusive and multilingual internet experience. Referencing Punycode - Wikipedia

Domain bindings for IDN hostnames in Azure App Service

There are several common ways to bind a domain to the Azure App Service, such as Azure portal, Azure CLI/ PowerShell, and ARM template. For domain bindings on the portal, it is not supported yet to add IDN hostnames. For now, we only support domains with alphanumeric characters (A-Z, a-z, 0-9), period ('.'), dash ('-'), and asterisk ('*') to be added.

For domain bindings with Azure CLI/ PowerShell/ ARM template, we could currently bypass this validation and could add those special punny code characters successfully. Referencing this blog: Create and bind the custom domain contains special Unicode character in App Service Using Azure CLI ...


Certificate validations for IDN hostnames in Azure App Service

To enable secure communication between the App Service and the client, a TLS/SSL certificate is necessary. There are two types of certificates to secure your domain: wildcard certificates and standard certificates. A wildcard certificate secures multiple subdomains under a single domain, while a standard certificate is specific to a single domain. In most use cases, a wildcard cert will be used to secure different subdomains as this is more manageable.
In the scenario of binding the certificate to the IDN hostnames, a wildcard cert is not recommended as it will encounter unexpected errors.
  • Error message:
"Code": "Conflict",
"Message": "The certificate with thumbprint 'xxx' does not match the hostname 'xxx€'."

  • Error screenshot:


Getting an error from PowerShell command lines as well




We are splitting the wildcard certificate when validating from the backend and this is why we are getting the unmatching error. The quickest workaround for now is to request a standard certificate specific to this hostname.



Overall, Azure App Service somehow enables you to configure domain bindings for IDN hostnames. You can associate an IDN hostname with your Azure App Service app with command lines. Additionally, you can manage the certificate bindings for these domains with standard certificates, ensuring security.
By leveraging Azure App Service's domain and certificate bindings, you can effectively host and secure websites with IDN hostnames, providing a more inclusive web experience for users across different languages and scripts.
Version history
Last update:
‎Jan 01 2024 10:18 PM
Updated by: