gregtampa / azurewebappsslmanager Goto Github PK

Azure WebApp SSL Manager is an Azure Function that acquires and manages free SSL certificates for Azure Web App and Azure Function App hosted applications.

Pre-Deployment
Before deploying this solution to Azure, you need to create a Service Principal (see below).
Unfortunately due to Azure ARM templates limitation it is not possible for me to include this step in the deployment.

Also, be sure to create your SendGrid API Key (see below).

Post-Deployment
After deploying the solution to Azure, make sure to set up the required configuration.
See the Application Properties Configuration File section below for more information

Azure WebApp SSL Manager is an Azure Function that acquires and manages free SSL certificates for applications hosted on Azure Web Apps and Azure Function Apps

Main Tasks performed:

• Order/Renewal of SSL certificates from Let's Encrypt free trusted CA
• Validation of the order using Azure DNS TXT record
• Download of the certificates and save them on Azure Blob Storage
• Installation of the certificates on Azure App Service Web App or Function App
• Association of the certificates to the Web App or Function App hostname bindings

Currently this solutions supports:

• Azure Web Apps
• Azure Web Apps Slots
• Azure Function Apps
• Azure Function Apps Slots

This project depends on few other project:

• Certes for the interface with Let's Encrypt services via ACME
• SendGrid for the email processing

In order to successfully use this application, you need a number of Prerequisites.

• Either:
  • At least one Azure Web App, with at least one custom domain assigned, running in Basic, Standard or Premium tier, OR
  • At least one Azure Function App, with at least one custom domain assigned, running in Consumption tier or in an App Service Basic, Standard or Premium tier
• A Blob storage account to save the App Properties configuration (see below) and to save the certificates
• The DNS for the custom domain must be managed via an Azure DNS Zone (in the same subscription of the resources)
• A Service Principal and it's config values
• A SendGrid account and a valid SendGrid API Key

Remember to bind all the hostnames you want to add certificates to to the App Service in advance.

You need to have a Service Principal to be able to perform management operations on Azure, like uploading the certificate to the App Service or managing the DNS Zone.

If you don't have a Service Principal, you can create one with the following command via Azure CLI. You can execute the command from any PC with the Azure CLI installed or from the Azure Shell

az ad sp create-for-rbac

You need to have enough privileges in your Azure AAD to be able to successfully create a Service Principal.

Visit the Azure Docs page for more information about Azure Service Principals creation.

Once created, take note of the output values, especially the password because it won't be possible to retrieve it later. The output will look like this:

{
  "appId": "xx15d42-f9xx-45xx-xx9a-3dxxxxxxxxf2",
  "displayName": "azure-cli-xxx-08-xx-07-xx-37",
  "name": "http://azure-cli-xxxx-08-xx-07-xx-37",
  "password": "7xxxxxx-xxxe-4xxx-xxxf-exxxxxxxxxx4",
  "tenant": "9xxxxxx0-cxxx-xxx4-bxxx-cxxxxxxxxxx3"
}

If you experience any problem with Service Principal, take a look at this wiki page.

AzureWebAppSSLManager sends emails using the Microsoft.Azure.WebJobs.Extensions.SendGrid extension, which needs a valid SendGrid API Key.

To obtain an API Key, you can follow the official SendGrid documentation

To be able to run, AzureWebAppSSLManager needs the following configuration settings.

They can be created in the Azure Web App configuration section when deployed, or in the local.settings.json file when debugging.

    "CertificateOwnerEmail": "[email protected]",
    "CertificatePassword": "YOUR_PASSWORD",
    "SubscriptionID": "SUBSCRIPTION_ID",
    "ServicePrincipalClientID": "SERVICE_PRINCIPAL_APP_ID",
    "ServicePrincipalClientSecret": "SERVICE_PRINCIPAL_PASSWORD",
    "ServicePrincipalTenantID": "SERVICE_PRINCIPAL_TENANT",
    "AzureStorageAccountConnectionString": "AZURE_STORAGE_FULL_CONNECTION_STRING",
    "SendGridKey": "SENDGRID_KEY",
    "EmailSender": "[email protected]",
    "UseStaging": "[True|False]",
    "BatchSize": [<0 for no batching> | <int>],
    "DaysBeforeExpiryToRenew": 30,
    "WebAppSSLManager-Trigger": "0 0 0 1 * *"

The config settings for the Service Principal are the ones from the output of the Service Principal creation above.

BatchSize is optional and defaults to 0.

DaysBeforeExpiryToRenew is optional and defaults to 30 (renew certificates 30 days before they expire).

WebAppSSLManager-Trigger is the the trigger configuration (i.e how frequently the Function will run, default every 1st day of each month)

Currently AzureWebAppSSLManager retrieves the list of certificates to generate and install from a json file stored in a blob storage account.

An example of the file structure can be found in the appproperties.json example file.

The file needs to be saved in a blob container with name as in the constant "AppPropertiesFileName" of the Constants.cs class.

The app retrieves some information needed for the certificate creation from a json file stored in a blob storage account.

An example of the file structure can be found in the certinfo.json example file.

The file needs to be saved in a blob container with name as in the constant "CertInfoFileName" of the Constants.cs class.

Currently an instance of AzureWebAppSSLManager can manage Web Apps and Function Apps in a single subscription. If you need/want to manage App Service Web Apps and Function Apps in multiple subscriptions, you would need to deploy one instance of this Function per subscription.

If you have any issue with this project please let me know through the Issues page and I'll try to fix the problem as soon as possible!

If you want to contribute to this project, feel free to create a Pull Request and I will review it.