forked from TrueCloudLab/lego
200 lines
8.8 KiB
TOML
200 lines
8.8 KiB
TOML
Name = "Azure DNS"
|
|
Description = ''''''
|
|
URL = "https://azure.microsoft.com/services/dns/"
|
|
Code = "azuredns"
|
|
Since = "v4.13.0"
|
|
|
|
Example = '''
|
|
### Using client secret
|
|
|
|
AZURE_CLIENT_ID=<your service principal client ID> \
|
|
AZURE_TENANT_ID=<your service principal tenant ID> \
|
|
AZURE_CLIENT_SECRET=<your service principal client secret> \
|
|
lego --domains example.com --email your_example@email.com --dns azuredns run
|
|
|
|
### Using client certificate
|
|
|
|
AZURE_CLIENT_ID=<your service principal client ID> \
|
|
AZURE_TENANT_ID=<your service principal tenant ID> \
|
|
AZURE_CLIENT_CERTIFICATE_PATH=<your service principal certificate path> \
|
|
lego --domains example.com --email your_example@email.com --dns azuredns run
|
|
|
|
### Using Azure CLI
|
|
|
|
az login \
|
|
lego --domains example.com --email your_example@email.com --dns azuredns run
|
|
|
|
### Using Managed Identity (Azure VM)
|
|
|
|
AZURE_TENANT_ID=<your service principal tenant ID> \
|
|
AZURE_RESOURCE_GROUP=<your target zone resource group name> \
|
|
lego --domains example.com --email your_example@email.com --dns azuredns run
|
|
|
|
### Using Managed Identity (Azure Arc)
|
|
|
|
AZURE_TENANT_ID=<your service principal tenant ID> \
|
|
IMDS_ENDPOINT=http://localhost:40342 \
|
|
IDENTITY_ENDPOINT=http://localhost:40342/metadata/identity/oauth2/token \
|
|
lego --domains example.com --email your_example@email.com --dns azuredns run
|
|
|
|
'''
|
|
|
|
Additional = '''
|
|
## Description
|
|
|
|
Several authentication methods can be used to authenticate against Azure DNS API.
|
|
|
|
### Default Azure Credentials (default option)
|
|
|
|
Default Azure Credentials automatically detects in the following locations and prioritized in the following order:
|
|
|
|
1. Environment variables for client secret: `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_SECRET`
|
|
2. Environment variables for client certificate: `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_CERTIFICATE_PATH`
|
|
3. Workload identity for resources hosted in Azure environment (see below)
|
|
4. Shared credentials (defaults to `~/.azure` folder), used by Azure CLI
|
|
|
|
Link:
|
|
- [Azure Authentication](https://learn.microsoft.com/en-us/azure/developer/go/azure-sdk-authentication)
|
|
|
|
### Environment variables
|
|
|
|
#### Service Discovery
|
|
|
|
Lego automatically finds all visible Azure (private) DNS zones using [Azure ResourceGraph query](https://learn.microsoft.com/en-us/azure/governance/resource-graph/).
|
|
This can be limited by specifying environment variable `AZURE_SUBSCRIPTION_ID` and/or `AZURE_RESOURCE_GROUP` which limits the
|
|
DNS zones to only a subscription or to one resourceGroup.
|
|
|
|
Additionally environment variable `AZURE_SERVICEDISCOVERY_FILTER` can be used to filter DNS zones with an addition Kusto filter eg:
|
|
|
|
```
|
|
resources
|
|
| where type =~ "microsoft.network/dnszones"
|
|
| ${AZURE_SERVICEDISCOVERY_FILTER}
|
|
| project subscriptionId, resourceGroup, name
|
|
```
|
|
|
|
|
|
#### Client secret
|
|
|
|
The Azure Credentials can be configured using the following environment variables:
|
|
* AZURE_CLIENT_ID = "Client ID"
|
|
* AZURE_CLIENT_SECRET = "Client secret"
|
|
* AZURE_TENANT_ID = "Tenant ID"
|
|
|
|
This authentication method can be specifically used by setting the `AZURE_AUTH_METHOD` environment variable to `env`.
|
|
|
|
#### Client certificate
|
|
|
|
The Azure Credentials can be configured using the following environment variables:
|
|
* AZURE_CLIENT_ID = "Client ID"
|
|
* AZURE_CLIENT_CERTIFICATE_PATH = "Client certificate path"
|
|
* AZURE_TENANT_ID = "Tenant ID"
|
|
|
|
This authentication method can be specifically used by setting the `AZURE_AUTH_METHOD` environment variable to `env`.
|
|
|
|
### Workload identity
|
|
|
|
Workload identity allows workloads running Azure Kubernetes Services (AKS) clusters to authenticate as an Azure AD application identity using federated credentials.
|
|
|
|
This must be configured in kubernetes workload deployment in one hand and on the Azure AD application registration in the other hand.
|
|
|
|
Here is a summary of the steps to follow to use it :
|
|
* create a `ServiceAccount` resource, add following annotations to reference the targeted Azure AD application registration : `azure.workload.identity/client-id` and `azure.workload.identity/tenant-id`.
|
|
* on the `Deployment` resource you must reference the previous `ServiceAccount` and add the following label : `azure.workload.identity/use: "true"`.
|
|
* create a federated credentials of type `Kubernetes accessing Azure resources`, add the cluster issuer URL and add the namespace and name of your kubernetes service account.
|
|
|
|
Link :
|
|
- [Azure AD Workload identity](https://azure.github.io/azure-workload-identity/docs/topics/service-account-labels-and-annotations.html)
|
|
|
|
This authentication method can be specifically used by setting the `AZURE_AUTH_METHOD` environment variable to `wli`.
|
|
|
|
### Azure Managed Identity
|
|
|
|
#### Azure Managed Identity (with Azure workload)
|
|
|
|
The Azure Managed Identity service allows linking Azure AD identities to Azure resources, without needing to manually manage client IDs and secrets.
|
|
|
|
Workloads with a Managed Identity can manage their own certificates, with permissions on specific domain names set using IAM assignments.
|
|
For this to work, the Managed Identity requires the **Reader** role on the target DNS Zone,
|
|
and the **DNS Zone Contributor** on the relevant `_acme-challenge` TXT records.
|
|
|
|
For example, to allow a Managed Identity to create a certificate for "fw01.lab.example.com", using Azure CLI:
|
|
|
|
```bash
|
|
export AZURE_SUBSCRIPTION_ID="00000000-0000-0000-0000-000000000000"
|
|
export AZURE_RESOURCE_GROUP="rg1"
|
|
export SERVICE_PRINCIPAL_ID="00000000-0000-0000-0000-000000000000"
|
|
|
|
export AZURE_DNS_ZONE="lab.example.com"
|
|
export AZ_HOSTNAME="fw01"
|
|
export AZ_RECORD_SET="_acme-challenge.${AZ_HOSTNAME}"
|
|
|
|
az role assignment create \
|
|
--assignee "${SERVICE_PRINCIPAL_ID}" \
|
|
--role "Reader" \
|
|
--scope "/subscriptions/${AZURE_SUBSCRIPTION_ID}/resourceGroups/${AZURE_RESOURCE_GROUP}/providers/Microsoft.Network/dnszones/${AZURE_DNS_ZONE}"
|
|
|
|
az role assignment create \
|
|
--assignee "${SERVICE_PRINCIPAL_ID}" \
|
|
--role "DNS Zone Contributor" \
|
|
--scope "/subscriptions/${AZURE_SUBSCRIPTION_ID}/resourceGroups/${AZURE_RESOURCE_GROUP}/providers/Microsoft.Network/dnszones/${AZURE_DNS_ZONE}/TXT/${AZ_RECORD_SET}"
|
|
```
|
|
|
|
A timeout wrapper is configured for this authentication method.
|
|
The duration can be configured by setting the `AZURE_AUTH_MSI_TIMEOUT`.
|
|
The default timeout is 2 seconds.
|
|
This authentication method can be specifically used by setting the `AZURE_AUTH_METHOD` environment variable to `msi`.
|
|
|
|
#### Azure Managed Identity (with Azure Arc)
|
|
|
|
The Azure Arc agent provides the ability to use a Managed Identity on resources hosted outside of Azure
|
|
(such as on-prem virtual machines, or VMs in another cloud provider).
|
|
|
|
While the upstream `azidentity` SDK will try to automatically identify and use the Azure Arc metadata service,
|
|
if you get `azuredns: DefaultAzureCredential: failed to acquire a token.` error messages,
|
|
you may need to set the environment variables:
|
|
* `IMDS_ENDPOINT=http://localhost:40342`
|
|
* `IDENTITY_ENDPOINT=http://localhost:40342/metadata/identity/oauth2/token`
|
|
|
|
A timeout wrapper is configured for this authentication method.
|
|
The duration can be configured by setting the `AZURE_AUTH_MSI_TIMEOUT`.
|
|
The default timeout is 2 seconds.
|
|
This authentication method can be specifically used by setting the `AZURE_AUTH_METHOD` environment variable to `msi`.
|
|
|
|
### Azure CLI
|
|
|
|
The Azure CLI is a command-line tool provided by Microsoft to interact with Azure resources.
|
|
It provides an easy way to authenticate by simply running `az login` command.
|
|
The generated token will be cached by default in the `~/.azure` folder.
|
|
|
|
This authentication method can be specifically used by setting the `AZURE_AUTH_METHOD` environment variable to `cli`.
|
|
|
|
### Open ID Connect
|
|
|
|
Open ID Connect is a mechanism that establish a trust relationship between a running environment and the Azure AD identity provider.
|
|
It can be enabled by setting the `AZURE_AUTH_METHOD` environment variable to `oidc`.
|
|
|
|
'''
|
|
|
|
[Configuration]
|
|
[Configuration.Credentials]
|
|
AZURE_CLIENT_ID = "Client ID"
|
|
AZURE_CLIENT_SECRET = "Client secret"
|
|
AZURE_TENANT_ID = "Tenant ID"
|
|
AZURE_CLIENT_CERTIFICATE_PATH = "Client certificate path"
|
|
[Configuration.Additional]
|
|
AZURE_ENVIRONMENT = "Azure environment, one of: public, usgovernment, and china"
|
|
AZURE_SUBSCRIPTION_ID = "DNS zone subscription ID"
|
|
AZURE_RESOURCE_GROUP = "DNS zone resource group"
|
|
AZURE_SERVICEDISCOVERY_FILTER = "Advanced ServiceDiscovery filter using Kusto query condition"
|
|
AZURE_PRIVATE_ZONE = "Set to true to use Azure Private DNS Zones and not public"
|
|
AZURE_ZONE_NAME = "Zone name to use inside Azure DNS service to add the TXT record in"
|
|
AZURE_AUTH_METHOD = "Specify which authentication method to use"
|
|
AZURE_AUTH_MSI_TIMEOUT = "Managed Identity timeout duration"
|
|
AZURE_TTL = "The TTL of the TXT record used for the DNS challenge"
|
|
AZURE_POLLING_INTERVAL = "Time between DNS propagation check"
|
|
AZURE_PROPAGATION_TIMEOUT = "Maximum waiting time for DNS propagation"
|
|
|
|
[Links]
|
|
API = "https://docs.microsoft.com/en-us/go/azure/"
|
|
GoClient = "https://github.com/Azure/azure-sdk-for-go"
|