Install a LetsEncrypt SSL Certificate into an Azure App Service

These are high-level notes from Troy Hunt's excellent blog post and the official Let's Encrypt Site Extension documentation.

Important: The LetsEncrypt site extension is currently buggy. Despite that it still works. Some errors we can simply ignore. We've done the following process on a few Azure Web Apps and each time some troubleshooting is necessary.

The following example sets up SSL for an App Service (named sapling) in an App Service Plan (named DefaultServerFarm). The App Service and App Service Plan are in different resource groups:

  • App Service sapling is in the TreeGame Resource Group.
  • App Service Plan DefaultServerFarm is in the Default-Web-WestUS Resource Group.

Note: Following these steps requires some thinking on your part... they are intentionally high level to respect your intelligence.

With that in mind, here are the steps we followed.

0. Add custom domain(s) to your Web App

This is fairly common Azure Web App knowledge, so I will not get into it here. It involve buying a custom domain name and wiring it via a CNAME or A record to the Azure Web App. Recommendation: use a CNAME unless you have a good reason to use an A record.

1. Setup Active Directory: add a server principal

Do this once per Active Directory tenant. So far we've needed only one tenant and that has been our default tenant.

  1. portal.azure.com
  2. Azure Active Directory
  3. Classic Portal
  4. Applications
  5. Add (this is a button near the bottom)
  6. Configure
  7. Copy Client ID. (we'll use this later).
  8. Keys > 2 years > Save > Copy (we'll use this later too).

Note: It is worth saving the ClientID and Key in a safe place. Alternatively, generate a new key each time we add SSL to a new Web App. To generate a new key, follow the step above until the Applications step and then.

  1. Choose LetsEncrpt (you've already created it).
  2. Configure
  3. Copy the Client ID.
  4. Generate and copy a new 2 year key.

2. Setup each Resource Group: give access to the server principal

Do this once per resource group. Since we have our Web App and App Service Plan living in separate Resource Groups, we needed to do this step twice.

  1. portal.azure.com
  2. Resource Groups
  3. For both DefaultWeb-WestUS and TreeGame
    • Access Control (IAM)
    • Add
    • Contributor
    • LetsEncrypt
    • Select > OK

3. Setup the Web App - add the site extension

Do this once per Web App that needs SSL.

Note: This is where the process become buggy and requires some creativity and persistence for it to succeed.

  1. From the Service Control Manager (https://sapling.scm.azurewebsites.net)
  2. Site Extensions > Gallery
  3. Search for Lets Encrypt
  4. Install the 32-bit extension
    • 64-bit explodes
  5. Restart the site
    • there is button at the top right

4. Setup the site extension

  1. Service Control Manager.
  2. Site Extensions > Installed
  3. Launch the site extension
  4. Set it up as follows:
    • Tenant mydirectory.onmicrosoft.com (find this in the top right corner of portal.azure.com)
    • SubscriptionId my-sub-script-ion-id (find this in the app service's overview page)
    • Client ID the Client ID of the LetsEncrypt Active Directory app that we created
    • Client Secret the Client Secret of the LetsEncrypt Active Directory app (its okay to create a new key if we lost it).
    • Resource Group Name TreeGame (i.e. use the Web App's Resource Group not the App Service Plan's one).
    • Service Plan Resource Group Name Default-Web-WestUS (here is where we use the App Service Plan's).
    • Use IP Based SSL false
    • Web App Name sapling (this is usually auto-filled)
    • Site Slot Name blank (unless your using a slot).
    • Update application settings true
  5. Click Next. If there is an error such as 'authority' Uri should have at least one segment in the path (i.e. https://<host>/<path>/...), simply refresh the page to resolve it.
  6. Click Next again to request and install a certificate.
    • Hostnames will be auto-filled with the App Service's custom domain name(s).
    • Email Add your email.
    • Use Staging false
    • Click Request and Install certificate. This might take a few minutes.
    • This might time outl if it does simply refresh the page; it has probably succeeded.

Visit the https:// URL associated with the hostnames from the most recent step. If it works, then you have succeeded!

Also visit the Environment page in the SCM, which will list all the letsencrypt related environment variables.