Add an SSL certificate in Azure App Service

Azure App Service provides a highly scalable, self-patching web hosting service. This article shows you how create, upload, or import a private certificate or a public certificate into App Service.

Once the certificate is added to your App Service app or function app, you can secure a custom DNS name with it or use it in your application code.

The following table lists the options you have for adding certificates in App Service:

Option Description
Create a free App Service Managed Certificate (Preview) A private certificate that's easy to use if you just need to secure your www custom domain or any non-naked domain in App Service.
Purchase an App Service certificate A private certificate that's managed by Azure. It combines the simplicity of automated certificate management and the flexibility of renewal and export options.
Import a certificate from Key Vault Useful if you use Azure Key Vault to manage your PKCS12 certificates. See Private certificate requirements.
Upload a private certificate If you already have a private certificate from a third-party provider, you can upload it. See Private certificate requirements.
Upload a public certificate Public certificates are not used to secure custom domains, but you can load them into your code if you need them to access remote resources.

Prerequisites

To follow this how-to guide:

Private certificate requirements

The free App Service Managed Certificate or the App Service certificate already satisfy the requirements of App Service. If you choose to upload or import a private certificate to App Service, your certificate must meet the following requirements:

  • Exported as a password-protected PFX file
  • Contains private key at least 2048 bits long
  • Contains all intermediate certificates in the certificate chain

To secure a custom domain in an SSL binding, the certificate has additional requirements:

  • Contains an Extended Key Usage for server authentication (OID = 1.3.6.1.5.5.7.3.1)
  • Signed by a trusted certificate authority

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.

Sign in to Azure

Open the Azure portal.

Search for and select App Services.

Select App Services

On the App Services page, select the name of your Azure app.

Portal navigation to Azure 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

Create a free certificate (Preview)

The free App Service Managed Certificate is a turn-key solution for securing your custom DNS name in App Service. It's a fully functional SSL certificate that's managed by App Service and renewed automatically. The free certificate comes with the following limitations:

  • Does not support wildcard certificates.
  • Does not support naked domains.
  • Is not exportable.

Note

The free certificate is issued by DigiCert. For some top-level domains, you must explicitly allow DigiCert as a certificate issuer by creating a CAA domain record with the value: 0 issue digicert.com.

To create a free App Service Managed Certificate:

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

From the left navigation of your app, select TLS/SSL settings > Private Key Certificates (.pfx) > Create App Service Managed Certificate.

Create free certificate in App Service

Any non-naked domain that's properly mapped to your app with a CNAME record is listed in the dialog. Select the custom domain to create a free certificate for and select Create. You can create only one certificate for each supported custom domain.

When the operation completes, you see the certificate in the Private Key Certificates list.

Create free certificate finished

Important

To secure a custom domain with this certificate, you still need to create a certificate binding. Follow the steps in Create binding.

Import an App Service Certificate

If you purchase an App Service Certificate from Azure, Azure manages the following tasks:

  • Takes care of the purchase process from GoDaddy.
  • Performs domain verification of the certificate.
  • Maintains the certificate in Azure Key Vault.
  • Manages certificate renewal (see Renew certificate).
  • Synchronize the certificate automatically with the imported copies in App Service apps.

To purchase an App Service certificate, go to Start certificate order.

If you already have a working App Service certificate, you can:

Start certificate order

Start an App Service certificate order in the App Service Certificate create page.

Start App Service certificate purchase

Use the following table to help you configure the certificate. When finished, click Create.

Setting Description
Name A friendly name for your App Service certificate.
Naked Domain Host Name Specify the root domain here. The issued certificate secures both the root domain and the www subdomain. In the issued certificate, the Common Name field contains the root domain, and the Subject Alternative Name field contains the www domain. To secure any subdomain only, specify the fully qualified domain name of the subdomain here (for example, mysubdomain.contoso.com).
Subscription The datacenter where the web app is hosted.
Resource group The resource group that contains the certificate. You can use a new resource group or select the same resource group as your App Service app, for example.
Certificate SKU Determines the type of certificate to create, whether a standard certificate or a wildcard certificate.
Legal Terms Click to confirm that you agree with the legal terms. The certificates are obtained from GoDaddy.

Store in Azure Key Vault

Once the certificate purchase process is complete, there are few more steps you need to complete before you can start using this certificate.

Select the certificate in the App Service Certificates page, then click Certificate Configuration > Step 1: Store.

Configure Key Vault storage of App Service certificate

Key Vault is an Azure service that helps safeguard cryptographic keys and secrets used by cloud applications and services. It's the storage of choice for App Service certificates.

In the Key Vault Status page, click Key Vault Repository to create a new vault or choose an existing vault. If you choose to create a new vault, use the following table to help you configure the vault and click Create. see to create new Key Vault inside same subscription and resource group.

Setting Description
Name A unique name that consists for alphanumeric characters and dashes.
Resource group As a recommendation, select the same resource group as your App Service certificate.
Location Select the same location as your App Service app.
Pricing tier For information, see Azure Key Vault pricing details.
Access policies Defines the applications and the allowed access to the vault resources. You can configure it later, following the steps at Grant several applications access to a key vault.
Virtual Network Access Restrict vault access to certain Azure virtual networks. You can configure it later, following the steps at Configure Azure Key Vault Firewalls and Virtual Networks

Once you've selected the vault, close the Key Vault Repository page. The Store option should show a green check mark for success. Keep the page open for the next step.

Verify domain ownership

From the same Certificate Configuration page you used in the last step, click Step 2: Verify.

Verify domain for App Service certificate

Select App Service Verification. Since you already mapped the domain to your web app (see Prerequisites), it's already verified. Just click Verify to finish this step. Click the Refresh button until the message Certificate is Domain Verified appears.

Note

Four types of domain verification methods are supported:

  • App Service - The most convenient option when the domain is already mapped to an App Service app in the same subscription. It takes advantage of the fact that the App Service app has already verified the domain ownership.
  • Domain - Verify an App Service domain that you purchased from Azure. Azure automatically adds the verification TXT record for you and completes the process.
  • Mail - Verify the domain by sending an email to the domain administrator. Instructions are provided when you select the option.
  • Manual - Verify the domain using either an HTML page (Standard certificate only) or a DNS TXT record. Instructions are provided when you select the option.

Import certificate into App Service

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

From the left navigation of your app, select TLS/SSL settings > Private Key Certificates (.pfx) > Import App Service Certificate.

Import App Service certificate in App Service

Select the certificate that you just purchased and select OK.

When the operation completes, you see the certificate in the Private Key Certificates list.

Import App Service certificate finished

Important

To secure a custom domain with this certificate, you still need to create a certificate binding. Follow the steps in Create binding.

Import a certificate from Key Vault

If you use Azure Key Vault to manage your certificates, you can import a PKCS12 certificate from Key Vault into App Service as long as it satisfies the requirements.

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

From the left navigation of your app, select TLS/SSL settings > Private Key Certificates (.pfx) > Import Key Vault Certificate.

Import Key Vault certificate in App Service)

Use the following table to help you select the certificate.

Setting Description
Subscription The subscription that the Key Vault belongs to.
Key Vault The vault with the certificate you want to import.
Certificate Select from the list of PKCS12 certificates in the vault. All PKCS12 certificates in the vault are listed with their thumbprints, but not all are supported in App Service.

When the operation completes, you see the certificate in the Private Key Certificates list. If the import fails with an error, the certificate doesn't meet the requirements for App Service.

Import Key Vault certificate finished

Important

To secure a custom domain with this certificate, you still need to create a certificate binding. Follow the steps in Create binding.

Upload a private certificate

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.

Upload certificate to App Service

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

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

From the left navigation of your app, select TLS/SSL settings > Private Key Certificates (.pfx) > Upload Certificate.

Upload private certificate in App Service

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

When the operation completes, you see the certificate in the Private Key Certificates list.

Upload certificate finished

Important

To secure a custom domain with this certificate, you still need to create a certificate binding. Follow the steps in Create binding.

Upload a public certificate

Public certificates are supported in the .cer format.

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

From the left navigation of your app, click TLS/SSL settings > Public Certificates (.cer) > Upload Public Key Certificate.

In Name, type a name for the certificate. In CER Certificate file, select your CER file.

Click Upload.

Upload public certificate in App Service

Once the certificate is uploaded, copy the certificate thumbprint and see Make the certificate accessible.

Manage App Service certificates

This section shows you how to manage an App Service certificate you purchased in Import an App Service certificate.

Rekey certificate

If you think your certificate's private key is compromised, you can rekey your certificate. Select the certificate in the App Service Certificates page, then select Rekey and Sync from the left navigation.

Click Rekey to start the process. This process can take 1-10 minutes to complete.

Rekey an App Service certificate

Rekeying your certificate rolls the certificate with a new certificate issued from the certificate authority.

Once the rekey operation is complete, click Sync. The sync operation automatically updates the hostname bindings for the certificate in App Service without causing any downtime to your apps.

Note

If you don't click Sync, App Service automatically syncs your certificate within 48 hours.

Renew certificate

To turn on automatic renewal of your certificate at any time, select the certificate in the App Service Certificates page, then click Auto Renew Settings in the left navigation. By default, App Service Certificates have a one-year validity period.

Select On and click Save. Certificates can start automatically renewing 60 days before expiration if you have automatic renewal turned on.

Renew App Service certificate automatically

To manually renew the certificate instead, click Manual Renew. You can request to manually renew your certificate 60 days before expiration.

Once the renew operation is complete, click Sync. The sync operation automatically updates the hostname bindings for the certificate in App Service without causing any downtime to your apps.

Note

If you don't click Sync, App Service automatically syncs your certificate within 48 hours.

Export certificate

Because an App Service Certificate is a Key Vault secret, you can export a PFX copy of it and use it for other Azure services or outside of Azure.

To export the App Service Certificate as a PFX file, run the following commands in the Cloud Shell. You can also run it locally if you installed Azure CLI. Replace the placeholders with the names you used when you created the App Service certificate.

secretname=$(az resource show \
    --resource-group <group-name> \
    --resource-type "Microsoft.CertificateRegistration/certificateOrders" \
    --name <app-service-cert-name> \
    --query "properties.certificates.<app-service-cert-name>.keyVaultSecretName" \
    --output tsv)

az keyvault secret download \
    --file appservicecertificate.pfx \
    --vault-name <key-vault-name> \
    --name $secretname \
    --encoding base64

The downloaded appservicecertificate.pfx file is a raw PKCS12 file that contains both the public and private certificates. In each prompt, use an empty string for the import password and the PEM pass phrase.

Delete certificate

Deletion of an App Service certificate is final and irreversible. Any binding in App Service with this certificate becomes invalid. To prevent accidental deletion, Azure puts a lock on the certificate. To delete an App Service certificate, you must first remove the delete lock on the certificate.

Select the certificate in the App Service Certificates page, then select Locks in the left navigation.

Find the lock on your certificate with the lock type Delete. To the right of it, select Delete.

Delete lock for App Service certificate

Now you can delete the App Service certificate. From the left navigation, select Overview > Delete. In the confirmation dialog, type the certificate name and select OK.

Automate with scripts

Azure CLI

#!/bin/bash

fqdn=<replace-with-www.{yourdomain}>
pfxPath=<replace-with-path-to-your-.PFX-file>
pfxPassword=<replace-with-your=.PFX-password>
resourceGroup=myResourceGroup
webappname=mywebapp$RANDOM

# Create a resource group.
az group create --location westeurope --name $resourceGroup

# Create an App Service plan in Basic tier (minimum required by custom domains).
az appservice plan create --name $webappname --resource-group $resourceGroup --sku B1

# Create a web app.
az webapp create --name $webappname --resource-group $resourceGroup \
--plan $webappname

echo "Configure a CNAME record that maps $fqdn to $webappname.azurewebsites.net"
read -p "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.

# Map your prepared custom domain name to the web app.
az webapp config hostname add --webapp-name $webappname --resource-group $resourceGroup \
--hostname $fqdn

# Upload the SSL certificate and get the thumbprint.
thumbprint=$(az webapp config ssl upload --certificate-file $pfxPath \
--certificate-password $pfxPassword --name $webappname --resource-group $resourceGroup \
--query thumbprint --output tsv)

# Binds the uploaded SSL certificate to the web app.
az webapp config ssl bind --certificate-thumbprint $thumbprint --ssl-type SNI \
--name $webappname --resource-group $resourceGroup

echo "You can now browse to https://$fqdn"

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.
New-AzWebApp -Name $webappname -Location $location -AppServicePlan $webappname `
-ResourceGroupName $webappname

Write-Host "Configure a CNAME record that maps $fqdn to $webappname.azurewebsites.net"
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