Tutorial: Bind an existing custom SSL certificate to Azure Web Apps

Azure Web Apps provides a highly scalable, self-patching web hosting service. This tutorial shows you how to bind a custom SSL certificate that you purchased from a trusted certificate authority to Azure Web Apps. When you're finished, you'll be able to access your web 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
  • Bind your custom certificate to App Service
  • Renew certificates
  • Enforce HTTPS
  • Enforce TLS 1.1/1.2
  • Automate TLS management with scripts

Note

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

Prerequisites

To complete this tutorial:

Requirements for your SSL certificate

To use a certificate in App Service, the certificate must meet all the following requirements:

  • 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

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.

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 to Upload and bind your SSL certificate.

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

Bind your SSL certificate

You are ready to upload your SSL certificate to your web app.

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.

Upload your SSL certificate

To upload your SSL certificate, click SSL settings in the left navigation of your web app.

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

When App Service finishes uploading your certificate, it appears in the SSL settings page.

Certificate uploaded

Bind your SSL certificate

In the SSL bindings section, click Add binding.

In the Add SSL Binding page, use the dropdowns to select the domain name to secure, and the certificate to use.

Note

If you have uploaded your certificate but don't see the domain name(s) in the Hostname dropdown, try refreshing the browser page.

In SSL Type, select whether to use Server Name Indication (SNI) or IP-based SSL.

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

Click Add Binding.

Bind SSL certificate

When App Service finishes uploading your certificate, it appears in the SSL bindings sections.

Certificate bound to web app

Remap A record for IP SSL

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

By default, your web 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 web app.

If you have mapped an A record to your web app, update your domain registry with this new, dedicated IP address.

Your web 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 web app.

Portal navigation to Azure app

Note

If your web 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 web app using HTTP. You can redirect all HTTP requests to the HTTPS port.

In your web 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 web 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 web 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 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

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

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

Public certificates (optional)

If your app needs to access remote resources as a client, and the remote resource requires certificate authentication, you can upload public certificates to your web app. Public certificates are not required for SSL bindings of your app.

For more details on loading and using a public certificate in your app, see Use an SSL certificate in your application code in Azure App Service. You can use public certificates with apps in App Service Environments too. If you need to store the certificate in the LocalMachine certificate store, you need to use a web app on App Service Environment. For more information, see How to configure public certificates to your Web App.

Upload Public Certificate

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.