Edit

Secure a custom DNS name with a TLS/SSL binding in Azure App Service

  • Article
  • 7 minutes to read

This article shows you how to secure the custom domain in your App Service app or function app by creating a certificate binding. When you're finished, you can access your App Service app at the https:// endpoint for your custom DNS name (for example, https://www.contoso.com).

Web app with custom TLS/SSL certificate

Securing a custom domain with a certificate involves two steps:

Prerequisites

To follow this how-to guide:

Note

The easiest way to add a private certificate is to create a free App Service managed certificate with your custom domain.

Prepare your web app

To create custom TLS/SSL bindings or enable client certificates for your App Service app, your App Service plan must be in the Basic, Standard, Premium, or Isolated tier. To make sure that your web app is in the supported pricing tier, follow these steps:

Go to your web app

  1. In the Azure portal search box, find and select App Services.

    Screenshot of Azure portal, search box, and "App Services" selected.

  2. On the App Services page, select your web app's name.

    Screenshot of the App Services page in Azure portal showing a list of all running web apps, with the first app in the list highlighted.

    You're now on your web app's management page.

Check the pricing tier

  1. In the left menu for your web app, under the Settings section, select Scale up (App Service plan).

    Screenshot of web app menu, "Settings" section, and "Scale up (App Service plan)" selected.

  2. Make sure that your web app isn't in the F1 or D1 tier, which doesn't support custom TLS/SSL.

    Your web app's current tier is highlighted by a dark blue box.

    Screenshot of web app pricing tier information.

  3. If you need to scale up, follow the steps in the next section. Otherwise, close the Scale up page, and skip the Scale up your App Service plan section.

Scale up your App Service plan

  1. Select any non-free tier, such as B1, B2, B3, or any other tier in the Production category. For more options, select See additional options.

  2. When you're done, select Apply.

    Screenshot of pricing tier and "Apply" selected.

    When the following message appears, the scale operation has completed.

    Screenshot with confirmation message for scale up operation.

Secure a custom domain

Do the following steps:

In the Azure portal, from the left menu, select App Services > <app-name>.

From the left navigation of your app, start the TLS/SSL Binding dialog by:

  • Selecting Custom domains > Add binding
  • Selecting TLS/SSL settings > Add TLS/SSL binding

Add binding to domain

In Custom Domain, select the custom domain you want to add a binding for.

If your app already has a certificate for the selected custom domain, go to Create binding directly. Otherwise, keep going.

Add a certificate for custom domain

If your app has no certificate for the selected custom domain, then you have two options:

Note

You can also Create a free certificate or Import a Key Vault certificate, but you must do it separately and then return to the TLS/SSL Binding dialog.

Create binding

Use the following table to help you configure the TLS binding in the TLS/SSL Binding dialog, then click Add Binding.

Setting Description
Custom domain The domain name to add the TLS/SSL binding for.
Private Certificate Thumbprint The certificate to bind.
TLS/SSL Type - SNI SSL: Multiple SNI SSL bindings may be added. This option allows multiple TLS/SSL certificates to secure multiple domains on the same IP address. Most modern browsers (including Internet Explorer, Chrome, Firefox, and Opera) support SNI (for more information, see Server Name Indication).
- IP SSL: Only one IP SSL binding may be added. This option allows only one TLS/SSL certificate to secure a dedicated public IP address. After you configure the binding, follow the steps in Remap records for IP SSL.
IP SSL is supported only in Standard tier or above.

Once the operation is complete, the custom domain's TLS/SSL state is changed to Secure.

TLS/SSL binding successful

Note

A Secure state in the Custom domains means that it is secured with a certificate, but App Service doesn't check if the certificate is self-signed or expired, for example, which can also cause browsers to show an error or warning.

Remap records for IP SSL

If you don't use IP SSL in your app, skip to Test HTTPS for your custom domain.

There are two changes you need to make, potentially:

  • By default, your app uses a shared public IP address. When you bind a certificate with IP SSL, App Service creates a new, dedicated IP address for your app. If you mapped an A record to your app, update your domain registry with this new, dedicated IP address.

    Your app's Custom domain page is updated with the new, dedicated IP address. Copy this IP address, then remap the A record to this new IP address.

  • If you have an SNI SSL binding to <app-name>.azurewebsites.net, remap any CNAME mapping to point to sni.<app-name>.azurewebsites.net instead (add the sni prefix).

Test HTTPS

In various browsers, browse to https://<your.custom.domain> to verify that it serves up your app.

Screenshot showing an example of browsing to your custom domain with the contoso.com URL highlighted.

Your application code can inspect the protocol via the "x-appservice-proto" header. The header will have a value of http or https.

Note

If your app gives you certificate validation errors, you're probably using a self-signed certificate.

If that's not the case, you may have left out intermediate certificates when you export your certificate to the PFX file.

Prevent IP changes

Your inbound IP address can change when you delete a binding, even if that binding is IP SSL. This is especially important when you renew a certificate that's already in an IP SSL binding. To avoid a change in your app's IP address, follow these steps in order:

  1. Upload the new certificate.
  2. Bind the new certificate to the custom domain you want without deleting the old one. This action replaces the binding instead of removing the old one.
  3. Delete the old certificate.

Enforce HTTPS

In your app page, in the left navigation, select TLS/SSL settings. Then, in HTTPS Only, select On.

If selected HTTPS Only, Off It means anyone can still access your app using HTTP. You can redirect all HTTP requests to the HTTPS port by selecting On.

Enforce HTTPS

When the operation is complete, navigate to any of the HTTP URLs that point to your app. For example:

  • http://<app_name>.azurewebsites.net
  • http://contoso.com
  • http://www.contoso.com

Enforce TLS versions

Your app allows TLS 1.2 by default, which is the recommended TLS level by industry standards, such as PCI DSS. To enforce different TLS versions, follow these steps:

In your app page, in the left navigation, select TLS/SSL settings. Then, in TLS version, select the minimum TLS version you want. This setting controls the inbound calls only.

Enforce TLS 1.1 or 1.2

When the operation is complete, your app rejects all connections with lower TLS versions.

Handle TLS termination

In App Service, TLS termination happens at the network load balancers, so all HTTPS requests reach your app as unencrypted HTTP requests. If your app logic needs to check if the user requests are encrypted or not, inspect the X-Forwarded-Proto header.

Language specific configuration guides, such as the Linux Node.js configuration guide, shows you how to detect an HTTPS session in your application code.

Automate with scripts

Azure CLI

Bind a custom TLS/SSL certificate to a web app

PowerShell

$fqdn="<Replace with your custom domain name>"
$pfxPath="<Replace with path to your .PFX file>"
$pfxPassword="<Replace with your .PFX password>"
$webappname="mywebapp$(Get-Random)"
$location="West Europe"

# Create a resource group.
New-AzResourceGroup -Name $webappname -Location $location

# Create an App Service plan in Free tier.
New-AzAppServicePlan -Name $webappname -Location $location `
-ResourceGroupName $webappname -Tier Free

# Create a web app.
$webapp = New-AzWebApp -Name $webappname -Location $location -AppServicePlan $webappname `
-ResourceGroupName $webappname

Write-Host "Sign in to your domain provider's website and configure the following records:"
Write-Host "A CNAME record that maps $fqdn to $webappname.azurewebsites.net"
Write-Host "A TXT record that maps asuid.$fqdn to the domain verification ID $($webapp.CustomDomainVerificationId)"
Read-Host "Press [Enter] key when ready ..."

# Before continuing, go to your DNS configuration UI for your custom domain and follow the 
# instructions at https://aka.ms/appservicecustomdns to configure a CNAME record for the 
# hostname "www" and point it your web app's default domain name.

# Upgrade App Service plan to Basic tier (minimum required by custom SSL certificates)
Set-AzAppServicePlan -Name $webappname -ResourceGroupName $webappname `
-Tier Basic

# Add a custom domain name to the web app. 
Set-AzWebApp -Name $webappname -ResourceGroupName $webappname `
-HostNames @($fqdn,"$webappname.azurewebsites.net")

# Upload and bind the SSL certificate to the web app.
New-AzWebAppSSLBinding -WebAppName $webappname -ResourceGroupName $webappname -Name $fqdn `
-CertificateFilePath $pfxPath -CertificatePassword $pfxPassword -SslState SniEnabled

More resources