Acmebot for Microsoft Azure

Acmebot is an automation tool for ACME SSL/TLS certificate issuance and renewal within Microsoft Azure. It is built around DNS-01 validation and uses Azure Key Vault to securely store private keys and issued certificates.

Key capabilities include:

• Automating certificate fleets with per-certificate renewal state.
• Centralizing certificates for multiple Azure services and domains.
• Monitoring operations via Application Insights and webhooks.
• Supporting zone apex names, wildcards, and SANs (Subject Alternative Names).

Acmebot supports two identity modes for the Function App:

1. System-assigned managed identity: Best for a single, isolated deployment.
2. User-assigned managed identity: Recommended for stable identities across redeployments or when using multiple apps. If using a user-assigned identity, the template sets the Acmebot__ManagedIdentityClientId app setting to the identity's Client ID.

Acmebot performs automated renewals using a daily timer. The renewal logic is designed to be ARI-aware (ACME Renewal Information) to optimize timing.

Renewal Logic

1. Discovery: The system lists certificates in Key Vault and filters for those tagged as Acmebot-managed and matching the current ACME endpoint.
2. ARI-Awareness: If the CA provides ARI, Acmebot uses the suggested window and Retry-After timing for the next check.
3. Fallback: If ARI is unavailable, Acmebot uses a RenewBeforeExpiry lifetime-percentage strategy.
4. Execution: Certificates are reissued using their stored Key Vault policy. When ARI is used, the previous certificate identifier is sent as the replaces parameter.

Error Handling

If a renewal fails, only that specific certificate enters a retrying state. It will be re-evaluated after a six-hour delay.

Long-running operations like certificate issuance (POST /api/certificates) and manual renewal (POST /api/certificates/{certificateName}/renew) follow an asynchronous pattern:

1. Initiate: Call the endpoint. It returns 202 Accepted with a Location header.
2. Resolve URL: The Location header contains a path relative to the original request. Resolve it against the base endpoint to get the polling URL.
3. Poll: Request the polling URL repeatedly until you receive one of the following:
   • 202 Accepted: The operation is still pending or running.
   • 200 OK: The operation completed successfully.
   • Problem response: The operation failed.

Acmebot uses the ACME DNS-01 validation method to issue certificates. The process follows these steps:

1. Record Creation: Acmebot creates one or more _acme-challenge TXT records in your DNS provider.
2. Propagation Wait: Acmebot waits for a predefined propagation delay (specific to the provider) to ensure the records are visible globally.
3. Validation: Acmebot asks the ACME server to validate the existence of these records.
4. Cleanup: Once validation is complete, Acmebot deletes the _acme-challenge TXT records.

To use this, you must configure at least one DNS provider under the Acmebot configuration section in your Function App settings before starting the app.

To use Acmebot effectively, understand these three core pillars:

Key Vault

Key Vault acts as the primary certificate store. Acmebot initiates certificate operations within Key Vault, allowing Key Vault to handle private key generation or reuse, and then merges the ACME-issued chain into the pending operation.

DNS Providers

Acmebot relies exclusively on DNS-01 validation. This method is required for wildcard certificates and allows for certificate issuance even if the target application is not publicly reachable. You must configure at least one DNS provider before deploying the Function App.

Certificate Authorities (CAs)

Acmebot supports ACME v2 directory endpoints. You can use common providers like Let's Encrypt, GlobalSign, Google Trust Services, SSL.com, and ZeroSSL, or provide a custom ACME directory URL via the deployment form.

Acmebot manages certificate renewals via the RenewCertificates timer, which runs daily for enabled managed certificates. Each certificate maintains its own renewal state and next check time.

Renewal logic follows these rules:

1. ARI-Aware Renewal: If the Certificate Authority (CA) provides ACME Renewal Information (ARI), Acmebot uses the CA's suggested renewal window and Retry-After timing. It renews after the suggested window has started.
2. Threshold-Based Renewal: If ARI is unavailable, Acmebot falls back to a percentage-based threshold. It renews when the remaining certificate lifetime is less than or equal to the value defined in Acmebot__RenewBeforeExpiry (default is 30%).

Note: Azure Functions timer schedules run in UTC unless the WEBSITE_TIME_ZONE setting is configured in the hosting plan.

Acmebot__RenewBeforeExpiry=30

The dashboard footer displays build metadata embedded by Vite. You can control the versioning and upgrade notification behavior by setting specific environment variables before running npm run build.

• Version-based Upgrades: If ACMEBOT_VERSION is set to a release-like value (e.g., v5.0.0), the dashboard will check GitHub releases (including prereleases) and display an upgrade notification if a newer version is found.
• Disabling Upgrade Checks: Setting the version to a non-version value like dev will skip the upgrade check.
• Commit Linking: Setting ACMEBOT_COMMIT_HASH allows the dashboard to link directly to the specific GitHub commit.