Tutorial: Upload and bind SSL certificates to Azure App Service

Azure App Service provides a highly scalable, self-patching web hosting service. This tutorial shows you how to secure a custom domain in App Service with a certificate that you purchased from a trusted certificate authority. It also shows you how to upload any private and public certificates your app needs. When you're finished, you'll be able to access your app at the HTTPS endpoint of your custom DNS domain.

Web app with custom SSL certificate

In this tutorial, you learn how to:

  • Upgrade your app's pricing tier
  • Secure a custom domain with a certificate
  • Upload a private certificate
  • Upload a public certificate
  • Renew certificates
  • Enforce HTTPS
  • Enforce TLS 1.1/1.2
  • Automate TLS management with scripts

Prerequisites

To complete this tutorial:

Prepare a private certificate

To secure a domain, the certificate must meet all the following requirements:

  • Configured for Server Authentication
  • Signed by a trusted certificate authority
  • Exported as a password-protected PFX file
  • Contains private key at least 2048 bits long
  • Contains all intermediate certificates in the certificate chain

Tip

If you need to get a custom SSL certificate, you can get one in the Azure portal directly and import it to your app. Follow the App Service Certificates tutorial.

Note

Elliptic Curve Cryptography (ECC) certificates can work with App Service but are not covered by this article. Work with your certificate authority on the exact steps to create ECC certificates.

Once you obtain a certificate from your certificate provider, follow the steps in this section to make it ready for App Service.

Merge intermediate certificates

If your certificate authority gives you multiple certificates in the certificate chain, you need to merge the certificates in order.

To do this, open each certificate you received in a text editor.

Create a file for the merged certificate, called mergedcertificate.crt. In a text editor, copy the content of each certificate into this file. The order of your certificates should follow the order in the certificate chain, beginning with your certificate and ending with the root certificate. It looks like the following example:

-----BEGIN CERTIFICATE-----
<your entire Base64 encoded SSL certificate>
-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----
<The entire Base64 encoded intermediate certificate 1>
-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----
<The entire Base64 encoded intermediate certificate 2>
-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----
<The entire Base64 encoded root certificate>
-----END CERTIFICATE-----

Export certificate to PFX

Export your merged SSL certificate with the private key that your certificate request was generated with.

If you generated your certificate request using OpenSSL, then you have created a private key file. To export your certificate to PFX, run the following command. Replace the placeholders <private-key-file> and <merged-certificate-file> with the paths to your private key and your merged certificate file.

openssl pkcs12 -export -out myserver.pfx -inkey <private-key-file> -in <merged-certificate-file>  

When prompted, define an export password. You'll use this password when uploading your SSL certificate to App Service later.

If you used IIS or Certreq.exe to generate your certificate request, install the certificate to your local machine, and then export the certificate to PFX.

You're now ready upload the certificate to App Service.

Prepare your web app

To bind a custom SSL certificate (a third-party certificate or App Service certificate) to your web app, your App Service plan must be in the Basic, Standard, Premium, or Isolated tier. In this step, you make sure that your web app is in the supported pricing tier.

Log in to Azure

Open the Azure portal.

From the left menu, click App Services, and then click the name of your web app.

Select web app

You have landed in the management page of your web app.

Check the pricing tier

In the left-hand navigation of your web app page, scroll to the Settings section and select Scale up (App Service plan).

Scale-up menu

Check to make sure that your web app is not in the F1 or D1 tier. Your web app's current tier is highlighted by a dark blue box.

Check pricing tier

Custom SSL is not supported in the F1 or D1 tier. 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

Select any of the non-free tiers (B1, B2, B3, or any tier in the Production category). For additional options, click See additional options.

Click Apply.

Choose pricing tier

When you see the following notification, the scale operation is complete.

Scale up notification

Secure a custom domain

Tip

If you need to get a custom SSL certificate, you can get one in the Azure portal directly and bind it to your app. Follow the App Service Certificates tutorial.

To secure a custom domain with a third-party certificate, you upload the prepared private certificate and then bind it to the custom domain, but App Service simplifies the process for you. Do the following steps:

Click Custom domains in the left navigation of your app, then click Add binding for the domain you want to secure. If you don't see Add binding for a domain, then it's already secure and should have a Secure SSL state.

Add binding to domain

Click Upload Certificate.

In PFX Certificate File, select your PFX file. In Certificate password, type the password that you created when you exported the PFX file.

Click Upload.

Upload certificate for domain

Wait for Azure to upload your certificate and launch the SSL bindings dialog.

In the SSL bindings dialog, select the certificate you uploaded and the SSL type, and then click Add Binding.

Note

The following SSL types are supported:

  • SNI-based SSL - Multiple SNI-based SSL bindings may be added. This option allows multiple SSL certificates to secure multiple domains on the same IP address. Most modern browsers (including Internet Explorer, Chrome, Firefox, and Opera) support SNI (find more comprehensive browser support information at Server Name Indication).
  • IP-based SSL - Only one IP-based SSL binding may be added. This option allows only one SSL certificate to secure a dedicated public IP address. To secure multiple domains, you must secure them all using the same SSL certificate. This is the traditional option for SSL binding.

Bind SSL to domain

The domain's SSL state should now be changed to Secure.

Domain secured

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 A record for IP SSL

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

By default, your app uses a shared public IP address. When you bind a certificate with IP-based SSL, App Service creates a new, dedicated IP address for your app.

If you have 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.

Test HTTPS

All that's left to do now is to make sure that HTTPS works for your custom domain. In various browsers, browse to https://<your.custom.domain> to see that it serves up your app.

Portal navigation to Azure app

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.

Renew certificates

Your inbound IP address can change when you delete a binding, even if that binding is IP-based. This is especially important when you renew a certificate that's already in an IP-based 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

By default, anyone can still access your app using HTTP. You can redirect all HTTP requests to the HTTPS port.

In your app page, in the left navigation, select SSL settings. Then, in HTTPS Only, select 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 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.

Automate with scripts

You can automate SSL bindings for your app with scripts, using the Azure CLI or Azure PowerShell.

Azure CLI

The following command uploads an exported PFX file and gets the thumbprint.

thumbprint=$(az webapp config ssl upload \
    --name <app-name> \
    --resource-group <resource-group-name> \
    --certificate-file <path-to-PFX-file> \
    --certificate-password <PFX-password> \
    --query thumbprint \
    --output tsv)

The following command adds an SNI-based SSL binding, using the thumbprint from the previous command.

az webapp config ssl bind \
    --name <app-name> \
    --resource-group <resource-group-name> \
    --certificate-thumbprint $thumbprint \
    --ssl-type SNI \

The following command forces the app to use https.

az webapp update \
    --name <app-name> \
    --resource-group <resource-group-name> \
    --https-only true

The following command enforces minimum TLS version of 1.2.

az webapp config set \
    --name <app-name> \
    --resource-group <resource-group-name> \
    --min-tls-version 1.2

Azure PowerShell

Note

This article has been updated to use the new Azure PowerShell Az module. You can still use the AzureRM module, which will continue to receive bug fixes until at least December 2020. To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. For Az module installation instructions, see Install Azure PowerShell.

The following command uploads an exported PFX file and adds an SNI-based SSL binding.

New-AzWebAppSSLBinding `
    -WebAppName <app_name> `
    -ResourceGroupName <resource_group_name> `
    -Name <dns_name> `
    -CertificateFilePath <path_to_PFX_file> `
    -CertificatePassword <PFX_password> `
    -SslState SniEnabled

Use certificates in your code

If your app needs to connect to remote resources, and the remote resource requires certificate authentication, you can upload public or private certificates to your app. You don't need to bind these certificates to any custom domain in your app. For more information, see Use an SSL certificate in your application code in Azure App Service.

Next steps

In this tutorial, you learned how to:

  • Upgrade your app's pricing tier
  • Bind your custom certificate to App Service
  • Renew certificates
  • Enforce HTTPS
  • Enforce TLS 1.1/1.2
  • Automate TLS management with scripts

Advance to the next tutorial to learn how to use Azure Content Delivery Network.

For more information, see Use an SSL certificate in your application code in Azure App Service.