Add and manage TLS/SSL certificates in Azure App Service

You can add digital security certificates to use in your application code or to help secure custom Domain Name System (DNS) names in Azure App Service. App Service provides a highly scalable, self-patching web hosting service. The certificates are currently called Transport Layer Security (TLS) certificates. They were previously known as Secure Sockets Layer (SSL) certificates. These private or public certificates help you to secure internet connections. The certificates encrypt data sent between your browser, websites that you visit, and the website server.

The following table lists the options for you to add certificates in App Service.

Prerequisites

• Create an App Service app. The app's App Service plan must be in the Basic, Standard, Premium, or Isolated tier. To update the tier, see Scale up an app.

• For a private certificate, make sure that it satisfies all requirements from App Service.

• Free certificate only:

  • Map the domain where you want the certificate to App Service. For more information, see Tutorial: Map an existing custom DNS name to Azure App Service.
  • For a root domain (like contoso.com), make sure that your app doesn't have any IP restrictions configured. Both certificate creation and its periodic renewal for a root domain depend on your app being reachable from the internet.

Private certificate requirements

The free App Service managed certificate and 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:

• Be exported as a password-protected .pfx file, encrypted by using triple DES.
• Contain a private key at least 2,048 bits long.
• Contain all intermediate certificates and the root certificate in the certificate chain.

If you want to help secure a custom domain in a TLS binding, the certificate must meet these extra requirements:

• Contain an extended key usage for server authentication (OID = 1.3.6.1.5.5.7.3.1).
• Be signed by a trusted certificate authority.

After you add a private certificate to an app, the certificate is stored in a deployment unit that's bound to the App Service plan's resource group, region, and operating system (OS) combination. Internally, it's called a webspace. That way, the certificate is accessible to other apps in the same resource group, region, and OS combination. Private certificates uploaded or imported to App Service are shared with app services in the same deployment unit.

You can add up to 1,000 private certificates per webspace.

Create a free managed certificate

The free App Service managed certificate is a turnkey solution that helps to secure your custom DNS name in App Service. App Service manages this TLS/SSL server certificate without any action from you.

Before you create a free managed certificate, make sure that you meet the prerequisites for your app.

DigiCert issues free certificates. For some domains, you must explicitly allow DigiCert as a certificate issuer by creating a Certification Authority Authorization (CAA) domain record with the value 0 issue digicert.com.

Azure fully manages the certificates for you, so any aspect of the managed certificate, including the root issuer, can change at any time. Certificate renewals change both public and private key parts. All of these certificate changes are outside of your control. Make sure to avoid hard dependencies and pinning practice certificates to the managed certificate or any part of the certificate hierarchy. If you need the certificate pinning behavior, add a certificate to your custom domain by using any other available method in this article.

The free certificate comes with the following limitations:

• Doesn't support wildcard certificates.
• Doesn't support use as a client certificate by using certificate thumbprints, which is planned for deprecation and removal.
• Doesn't support private DNS.
• Isn't exportable.
• Isn't supported in App Service Environment.
• Supports only alphanumeric characters, dashes (-), and periods (.).
• Supports custom domains of a length up to 64 characters.

1. In the Azure portal, on the left pane, select App Services > <app-name>.

2. On the left pane of your app, select Certificates. On the Managed certificates pane, select Add certificate.

   

3. Select the custom domain for the free certificate, and then select Validate. When validation finishes, select Add. You can create only one managed certificate for each supported custom domain.

   After the operation finishes, the certificate appears in the Managed certificates list.

   

4. To provide security for a custom domain with this certificate, you must create a certificate binding. Follow the steps in Secure a custom DNS name with a TLS/SSL binding in Azure App Service.

Import an App Service certificate

To import an App Service certificate, first buy and configure an App Service certificate, and then follow the steps here.

1. In the Azure portal, on the left pane, select App Services > <app-name>.

2. On the left pane of your app, select Certificates > Bring your own certificates (.pfx) > Add certificate.

3. Under Source, select Import App Service Certificate.

4. Under App Service certificate, select the certificate that you created.

5. Under Certificate friendly name, give the certificate a name in your app.

6. Select Validate. When validation succeeds, select Add.

   

   After the operation finishes, the certificate appears in the Bring your own certificates (.pfx) list.

   

7. To help secure a custom domain with this certificate, you must create a certificate binding. Follow the steps in Secure a custom DNS name with a TLS/SSL binding in Azure App Service.

Import a certificate from Key Vault

If you use Key Vault to manage your certificates, you can import a PKCS12 certificate into App Service from Key Vault if you meet the requirements.

Authorize App Service to read from the vault

By default, the App Service resource provider doesn't have access to your key vault. To use a key vault for a certificate deployment, you must authorize read access for the resource provider (App Service) to the key vault. You can grant access with an access policy or role-based access control (RBAC).

az role assignment create --role "Key Vault Certificate User" --assignee "abfa0a7c-a6b6-4736-8310-5855508787cd" --scope "/subscriptions/{subscriptionid}/resourcegroups/{resource-group-name}/providers/Microsoft.KeyVault/vaults/{key-vault-name}"

#Assign by Service Principal ApplicationId
New-AzRoleAssignment -RoleDefinitionName "Key Vault Certificate User" -ApplicationId "abfa0a7c-a6b6-4736-8310-5855508787cd" -Scope "/subscriptions/{subscriptionid}/resourcegroups/{resource-group-name}/providers/Microsoft.KeyVault/vaults/{key-vault-name}"

Import a certificate from your vault to your app

1. In the Azure portal, on the left pane, select App Services > <app-name>.

2. On the left pane of your app, select Certificates > Bring your own certificates (.pfx) > Add certificate.

3. Under Source, select Import from Key Vault.

4. Choose Select key vault certificate.

   

5. To help you select the certificate, use the following table:

   Setting	Description
   Subscription	The subscription associated with the key vault.
   Key Vault	The key vault that has the certificate you want to import.
   Certificate	From this list, select a PKCS12 certificate that's in the vault. All PKCS12 certificates in the vault are listed with their thumbprints, but not all are supported in App Service.

6. After you finish with your selection, choose Select > Validate, and then select Add.

   After the operation finishes, the certificate appears in the Bring your own certificates (.pfx) list. If the import fails with an error, the certificate doesn't meet the requirements for App Service.

   

   If you update your certificate in Key Vault with a new certificate, App Service automatically syncs your certificate within 24 hours.

7. To help secure a custom domain with this certificate, you must create a certificate binding. Follow the steps in Secure a custom DNS name with a TLS/SSL binding in Azure App Service.

Upload a private certificate

After you get a certificate from your certificate provider, make the certificate ready for App Service by following the steps in this section.

Merge intermediate certificates

If your certificate authority gives you multiple certificates in the certificate chain, you must merge the certificates by following the same order.

1. In a text editor, open each received certificate.

2. To store the merged certificate, create a file named mergedcertificate.crt.

3. Copy the content for each certificate into this file. Make sure to follow the certificate sequence specified by the certificate chain. Start with your certificate and end with the root certificate, for 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 the merged private certificate to .pfx

Now, export your merged TLS/SSL certificate with the private key that was used to generate your certificate request. If you generated your certificate request by using OpenSSL, then you created a private key file.

OpenSSL v3 changed the default cipher from 3DES to AES256. Use the command line -keypbe PBE-SHA1-3DES -certpbe PBE-SHA1-3DES -macalg SHA1 to override the change.

OpenSSL v1 uses 3DES as the default, so the .pfx files that are generated are supported without any special modifications.

1. To export your certificate to a .pfx file, 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>  
   

2. When you're prompted, specify a password for the export operation. When you upload your TLS/SSL certificate to App Service later, you must provide this password.

3. If you used IIS or Certreq.exe to generate your certificate request, install the certificate to your local computer, and then export the certificate to a .pfx file.

Upload the certificate to App Service

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

1. In the Azure portal, on the left pane, select App Services > <app-name>.

2. On the left pane of your app, select Certificates > Bring your own certificates (.pfx) > Upload certificate (.pfx).

   

3. To help you upload the .pfx certificate, use the following table:

   Setting	Description
   PFX certificate file	Select your .pfx file.
   Certificate password	Enter the password that you created when you exported the .pfx file.
   Certificate friendly name	The certificate name that appears in your web app.

4. After you finish with your selection, choose Select > Validate, and then select Add.

   After the operation finishes, the certificate appears in the Bring your own certificates (.pfx) list.

   

5. To provide security for a custom domain with this certificate, you must create a certificate binding. Follow the steps in Secure a custom DNS name with a TLS/SSL binding in Azure App Service.

Upload a public certificate

Public certificates are supported in the .cer format.

After you upload a public certificate to an app, it's accessible only by the app to which it's uploaded. Public certificates must be uploaded to each individual web app that needs access. For scenarios specific to App Service Environment, refer to the documentation for certificates and App Service Environment.

You can upload up to 1,000 public certificates per App Service plan.

1. In the Azure portal, on the left pane, select App Services > <app-name>.

2. On the left pane of your app, select Certificates > Public key certificates (.cer) > Add certificate.

3. To help you upload the .cer certificate, use the following table:

   Setting	Description
   .cer certificate file	Select your .cer file.
   Certificate friendly name	The certificate name that appears in your web app.

4. After you finish, select Add.

   

5. After the certificate is uploaded, copy the certificate thumbprint, and then review Make the certificate accessible.

Renew an expiring certificate

Before a certificate expires, make sure to add the renewed certificate to App Service. Update any certificate bindings where the process depends on the certificate type. For example, a certificate imported from Key Vault, including an App Service certificate, automatically syncs to App Service every 24 hours and updates the TLS/SSL binding when you renew the certificate.

For an uploaded certificate, there's no automatic binding update. Based on your scenario, review the corresponding section:

• Renew an uploaded certificate
• Renew an App Service certificate
• Renew a certificate imported from Key Vault

Renew an uploaded certificate

When you replace an expiring certificate, the way you update the certificate binding with the new certificate might adversely affect the user experience. For example, your inbound IP address might change when you delete a binding, even if that binding is IP based. This result is especially effective when you renew a certificate that's already in an IP-based binding.

To avoid a change in your app's IP address, and to avoid downtime for your app because of HTTPS errors, follow these steps:

1. Upload the new certificate.

2. Go to the Custom domains page for your app, select the ... button, and then select Update binding.

3. Select the new certificate, and then select Update.

4. Delete the existing certificate.

Renew a certificate imported from Key Vault

To renew an App Service certificate, see Renew an App Service certificate.

To renew a certificate that you imported into App Service from Key Vault, see Renew your Azure Key Vault certificate.

After the certificate renews in your key vault, App Service automatically syncs the new certificate and updates any applicable certificate binding within 24 hours. To sync manually, follow these steps:

1. Go to your app's Certificate page.

2. Under Bring your own certificates (.pfx), select the ... button for the imported key vault certificate, and then select Sync.

Frequently asked questions

How can I automate the process of adding a bring-your-own certificate to an app?

• Azure CLI: Bind a custom TLS/SSL certificate to a web app
• Azure PowerShell: Bind a custom TLS/SSL certificate to a web app by using PowerShell

Can I use a private CA certificate for inbound TLS on my app?

You can use a private certificate authority (CA) certificate for inbound TLS in App Service Environment version 3. This action isn't possible in App Service (multitenant). For more information on App Service multitenant versus single tenant, see App Service Environment v3 and App Service public multitenant comparison.

Can I make outbound calls by using a private CA client certificate from my app?

This capability is supported for Windows container apps only in multitenant App Service. You can make outbound calls by using a private CA client certificate with both code-based and container-based apps in App Service Environment version 3. For more information on App Service multitenant versus single tenant, see App Service Environment v3 and App Service public multitenant comparison.

Can I load a private CA certificate in my App Service trusted root store?

You can load your own CA certificate into the trusted root store in App Service Environment version 3. You can't modify the list of trusted root certificates in App Service (multitenant). For more information on App Service multitenant versus single tenant, see App Service Environment v3 and App Service public multitenant comparison.

Can App Service certificates be used for other services?

Yes. You can export and use App Service certificates with Azure Application Gateway or other services. For more information, see the blog article Creating a local PFX copy of App Service Certificate.

Related content

• Secure a custom DNS name with a TLS/SSL binding in Azure App Service
• Enforce HTTPS
• Enforce TLS 1.1/1.2
• Use a TLS/SSL certificate in your code in Azure App Service
• FAQ: App Service certificates