Add and manage TLS/SSL certificates in Azure App Service
You can add digital security certificates to use in your application code or to secure custom DNS names in Azure App Service, which provides a highly scalable, self-patching web hosting service. Currently called Transport Layer Security (TLS) certificates, also previously known as Secure Socket Layer (SSL) certificates, these private or public certificates help you secure internet connections by encrypting 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:
| Option | Description |
|---|---|
| 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 aren't used to secure custom domains, but you can load them into your code if you need them to access remote resources. |
Prerequisites
Create an App Service app. The app's App Service plan must be in the Basic, Standard, Premium, or Isolated tier. See Scale up an app to update the tier.
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 information, see Tutorial: Map an existing custom DNS name to Azure App Service.
For a root domain (like contoso.com), make sure your app doesn't have any IP restrictions configured. Both certificate creation and its periodic renewal for a root domain depends on your app being reachable from the internet.
Private certificate requirements
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, encrypted using triple DES.
- Contains private key at least 2048 bits long
- Contains all intermediate certificates and the root certificate in the certificate chain.
To secure a custom domain in a TLS binding, the certificate has more 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 work with App Service but aren't covered by this article. For the exact steps to create ECC certificates, work with your certificate authority.
Note
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 combination, internally 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 1000 private certificates per webspace.
Import a certificate from Key Vault
If you use Azure Key Vault to manage your certificates, you can import a PKCS12 certificate into App Service from Key Vault if you met 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 to the key vault.
Note
Currently, a Key Vault certificate supports only the Key Vault access policy, not RBAC model.
| Resource provider | Service principal AppId | Key vault secret permissions | Key vault certificate permissions |
|---|---|---|---|
| Azure App Service or Microsoft.Azure.WebSites | - abfa0a7c-a6b6-4736-8310-5855508787cd, which is the same for all Azure subscriptions . |
Get | Get |
| Microsoft.Azure.CertificateRegistration | Get List Set Delete |
Get List |
Import a certificate from your vault to your app
In the Azure portal, from the left menu, select App Services > <app-name>.
From your app's navigation menu, select Certificates > Bring your own certificates (.pfx) > Add certificate.
In Source, select Import from Key Vault.
Select Select key vault certificate.
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. When finished with your selection, select Select, Validate, then Add.
When the operation completes, the certificate appears in the Bring your own certificates list. If the import fails with an error, the certificate doesn't meet the requirements for App Service.
Note
If you update your certificate in Key Vault with a new certificate, App Service automatically syncs your certificate within 24 hours.
To secure a custom domain with this certificate, you still have to 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 following the same order.
In a text editor, open each received certificate.
To store the merged certificate, create a file named mergedcertificate.crt.
Copy the content for each certificate into this file. Make sure to follow the certificate sequence specified by the certificate chain, starting with your certificate and ending 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 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 using OpenSSL, then you created a private key file.
Note
OpenSSL v3 changed default cipher from 3DES to AES256, but this can be overridden on the command line -keypbe PBE-SHA1-3DES -certpbe PBE-SHA1-3DES -macalg SHA1. OpenSSL v1 uses 3DES as default, so the PFX files generated are supported without any special modifications.
To export your certificate to a PFX file, run the following command, but 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 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.
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 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 your app's navigation menu, select Certificates > Bring your own certificates (.pfx) > Upload Certificate.
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 will be shown in your web app. When finished with your selection, select Select, Validate, then Add.
When the operation completes, the certificate appears in the Bring your own certificates list.
To secure a custom domain with this certificate, you still have to 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.
Note
After you upload a public certificate to an app, it is only accessible by the app it is uploaded to. Public certificates must be uploaded to each individual web app that needs access. For App Service Environment specific scenarios, refer to the documentation for certificates and the App Service Environment
You can upload up to 1000 public certificates per App Service Plan.
In the Azure portal, from the left menu, select App Services > <app-name>.
From your app's navigation menu, select Certificates > Public key certificates (.cer) > Add certificate.
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 will be shown in your web app. When you're done, select Add.
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, and 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 uploaded certificate
When you replace an expiring certificate, the way you update the certificate binding with the new certificate might adversely affect 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 impactful 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 due to HTTPS errors, follow these steps in the specified sequence:
Go to the Custom domains page for your app, select the ... actions button, and select Update binding.
Select the new certificate and select Update.
Delete the existing certificate.
Renew a certificate imported from Key Vault
To renew a certificate that you imported into App Service from Key Vault, review Renew your Azure Key Vault certificate.
After the certificate renews inside 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:
Go to your app's Certificate page.
Under Bring your own certificates (.pfx), select the ... details button for the imported key vault certificate, and then select Sync.
Frequently asked questions
How can I automate adding a bring-your-owncertificate 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 using PowerShell
Can I configure a private CA certificate on my app?
App Service has a list of Trusted Root Certificates which you cannot modify in the multi-tenant variant version of App Service, but you can load your own CA certificate in the Trusted Root Store in an App Service Environment (ASE), which is a single-tenant environment in App Service. (The Free, Basic, Standard, and Premium App Service Plans are all multi-tenant, and the Isolated Plans are single-tenant.)