You can use Let's Encrypt certificates to secure a custom domain hosted by Azure App Service; this page is for administrators configuring automatic certificate renewal through the Azure Let's Encrypt extension.

Let's Encrypt issues free TLS/SSL certificates with a 90-day validity period. The Azure extension described here requests certificates for your Azure App Service custom domains and uses an Azure Storage account while it operates and renews certificates.

Before you begin

Confirm the following before configuring the extension:

• Your application is hosted in an Azure App Service.
• Each domain that needs a certificate has been added as a custom domain on the App Service.
• The domain name resolves to the App Service and can be reached over HTTP during certificate issuance.
• You can administer the Azure subscription, resource group, App Service, storage account, and Microsoft Entra ID (Azure AD) application registration.
• You have a storage account available, or you can create one for the extension data.

For example, if users access Turnkey at https://app.example.com, add app.example.com as a custom domain before requesting its certificate.

Do not use this procedure for an MDriven installation hosted behind Nginx on Ubuntu. Follow Documentation:Serving MDriven with Nginx Server as a Proxy instead; it uses Certbot and Nginx to obtain and renew Let's Encrypt certificates.

Configure Azure resources

1. Add the custom domain

In the Azure portal, open your App Service and add the domain name that you want to protect as a custom domain. Complete the required DNS configuration for that domain.

Repeat this for every domain that requires its own certificate. For example, add both app.example.com and www.example.com if both are public entry points.

2. Create or select a storage account

Create a storage account or select an existing one. The Azure Let's Encrypt extension stores its data in this account.

Copy the storage-account connection string. You will use the same value for two App Service connection-string settings in a later step. Treat the connection string as a secret because it provides access to the storage account.

3. Create an application registration

Create an Azure AD application registration for the Let's Encrypt extension. Give it a name that identifies its purpose, such as MyAppLetsEncrypt.

Record the application's Application (client) ID. Create a client secret and record its value securely. The original configuration procedure uses login as the secret name.

4. Grant access to the resource group

The application registration must be allowed to work with the Azure resources in the resource group that contains the App Service.

1. Open the resource group that runs the App Service.
2. Open its access-control settings.
3. Add a role assignment for the application registration created in the previous step.
4. Assign the Contributor role.

For example, assign Contributor on the ProductionApps resource group to MyAppLetsEncrypt. Grant access only to the resource group required by the extension.

Configure the Azure Let's Encrypt extension

1. Add the required connection strings

1. In the Azure portal, open the App Service.
2. Open the App Service connection-string settings.
3. Add the following two connection strings. Set both values to the storage-account connection string copied earlier.

Name	Value	Purpose
AzureWebJobsDashboard	Storage-account connection string	Storage used by the extension.
AzureWebJobsStorage	Storage-account connection string	Storage used by the extension.

Both settings must use the same storage-account connection string. Save the App Service settings.

2. Open and configure the extension

1. In the Azure portal, open the App Service.
2. Open Extensions.
3. Select the Azure Let's Encrypt extension.
4. Open its configuration page at http://YOUR-SITE-NAME.scm.azurewebsites.net/LetsEncrypt, replacing YOUR-SITE-NAME with the App Service site name.
5. Follow the extension's configuration screens. Provide the Azure AD application registration details and select the resource group and storage resources required by the extension.

The configuration uses the application registration to access Azure resources and the storage connection strings to persist extension data.

Request and install certificates

After the extension is configured, its page displays the available custom domain names.

1. Select one domain.
2. Choose Request and Install.
3. Wait for the request and installation to complete.
4. Repeat for each additional custom domain.

For example, request and install a certificate for app.example.com, then repeat the process for www.example.com if that domain is also configured.

Bind certificates and require HTTPS

After certificates have been requested:

1. Return to the App Service custom-domain configuration.
2. Select the installed certificate for each custom domain.
3. Save the certificate binding.
4. Enable the App Service setting that forces HTTPS, referred to in the original procedure as Always SSL.

Test each public URL with https://. Confirm that the domain name in the browser matches the domain bound to the certificate.

Troubleshooting

The domain is not available in the extension

Verify that the domain has first been added as an App Service custom domain and that its DNS records point to the App Service. The extension can only request certificates for configured domains.

Certificate request fails

Check these items:

• The domain is publicly resolvable and reachable over HTTP.
• The App Service connection strings are named exactly AzureWebJobsDashboard and AzureWebJobsStorage.
• Both connection strings contain the intended storage-account connection string.
• The Azure AD application registration has a valid client secret.
• The application registration has the Contributor role on the resource group that contains the App Service.

HTTPS does not serve the expected certificate

Verify that the installed certificate is bound to the affected custom domain in the App Service configuration. A certificate installed by the extension still needs to be selected for the relevant custom-domain binding.

Related certificate guidance

This page covers Azure App Service certificate issuance through the Azure Let's Encrypt extension. For certificate concepts and other deployment scenarios, see Documentation:Certificate, Documentation:SSL/TLS settings, and Documentation:LocalhostDevCert.

See also

• Documentation:Certificate
• Documentation:SSL/TLS settings
• Documentation:LocalhostDevCert
• Documentation:Serving MDriven with Nginx Server as a Proxy