Skip to content

Commit 1e7ed48

Browse files
bhillkeyfactorbhillkeyfactor
authored
Merge pull request #24 from Keyfactor/cname-delegation-dnsplugins
Cname delegation dnsplugins
2 parents fae7b6a + a19cce6 commit 1e7ed48

2 files changed

Lines changed: 56 additions & 273 deletions

File tree

‎README.md‎

Lines changed: 28 additions & 136 deletions
Original file line numberDiff line numberDiff line change
@@ -52,17 +52,14 @@ This plugin has been tested and confirmed to work with the following ACME provid
5252

5353
It is designed to be provider-agnostic and should work with any standards-compliant ACME server.
5454

55-
### 🌐 Supported DNS Providers
56-
DNS-01 challenge automation is supported through the following providers:
57-
- **Google Cloud DNS**
58-
- **AWS Route 53**
59-
- **Azure DNS**
60-
- **Cloudflare**
61-
- **NS1**
62-
- **Infoblox**
63-
- **RFC 2136 Dynamic DNS** (BIND with TSIG authentication)
64-
65-
Additional DNS providers can be added by extending the included `IDnsProvider` interface.
55+
### 🌐 DNS Providers (Pluggable)
56+
DNS-01 challenge automation is handled by **separate, pluggable DNS provider plugins** that are deployed alongside the AnyCA Gateway — they are no longer built into this plugin. The Gateway resolves the appropriate DNS provider plugin per domain at enrollment time.
57+
58+
For the current list of available DNS provider plugins, see the Keyfactor GitHub organization:
59+
60+
👉 **[Keyfactor DNS provider plugins (`-dnsplugin`)](https://github.com/orgs/Keyfactor/repositories?q=-dnsplugin)**
61+
62+
Each plugin repository documents its own supported authentication methods and configuration keys. New DNS providers can be added by publishing a new plugin that implements the Gateway's `IDomainValidator` interface — no change to this ACME plugin is required.
6663

6764
---
6865

@@ -102,17 +99,15 @@ The Acme AnyCA Gateway REST plugin is supported by Keyfactor for Keyfactor custo
10299
This plugin automates DNS-01 challenges using pluggable DNS provider implementations. These providers create and remove TXT records to prove domain control to ACME servers.
103100

104101
<details>
105-
<summary><strong>✅ Supported DNS Providers</strong></summary>
106-
107-
| Provider | Auth Methods Supported | Config Keys Required |
108-
|--------------|-----------------------------------------------|--------------------------------------------------------|
109-
| Google DNS | Service Account Key (file or JSON), or ADC | `Google_ServiceAccountKeyPath`, `Google_ServiceAccountKeyJson`, `Google_ProjectId` |
110-
| AWS Route 53 | Access Key/Secret or IAM Role | `AwsRoute53_AccessKey`, `AwsRoute53_SecretKey` |
111-
| Azure DNS | Client Secret or Managed Identity | `Azure_TenantId`, `Azure_ClientId`, `Azure_ClientSecret`, `Azure_SubscriptionId` |
112-
| Cloudflare | API Token | `Cloudflare_ApiToken` |
113-
| NS1 | API Key | `Ns1_ApiKey` |
114-
| Infoblox | Username/Password (Basic Auth) | `Infoblox_Host`, `Infoblox_Username`, `Infoblox_Password` |
115-
| RFC 2136 | TSIG Key (BIND) | `Rfc2136_Server`, `Rfc2136_Zone`, `Rfc2136_TsigKeyName`, `Rfc2136_TsigKey` |
102+
<summary><strong>🔌 Available DNS Provider Plugins</strong></summary>
103+
104+
DNS providers are distributed as **standalone plugins**, each in its own repository, and are deployed alongside the AnyCA Gateway rather than bundled into this ACME plugin. This lets you add or upgrade a DNS provider without rebuilding the ACME plugin.
105+
106+
For the current, authoritative list of available DNS provider plugins, query the Keyfactor GitHub organization:
107+
108+
👉 **[github.com/orgs/Keyfactor/repositories?q=-dnsplugin](https://github.com/orgs/Keyfactor/repositories?q=-dnsplugin)**
109+
110+
Each plugin's own repository is the source of truth for its supported authentication methods, required configuration keys, and setup instructions. Configure the DNS provider(s) through the AnyCA Gateway's **Domain Validation** configuration; the Gateway resolves the correct plugin per domain at enrollment time.
116111

117112
</details>
118113

@@ -178,133 +173,34 @@ Resolution + placement:
178173
</details>
179174

180175
<details>
181-
<summary><strong>🔑 Credential Flow</strong></summary>
182-
183-
Each provider supports multiple credential strategies:
184-
185-
- **Google DNS**:
186-
- ✅ **Service Account Key File** (via `Google_ServiceAccountKeyPath`)
187-
- ✅ **Service Account Key JSON** (via `Google_ServiceAccountKeyJson` - paste JSON directly)
188-
- ✅ **Application Default Credentials** (e.g., GCP Workload Identity or developer auth)
176+
<summary><strong>🔑 Provider Credentials &amp; Configuration</strong></summary>
189177

190-
- **AWS Route 53**:
191-
- ✅ **Access/Secret Keys** (`AwsRoute53_AccessKey`, `AwsRoute53_SecretKey`)
192-
- ✅ **IAM Role via EC2 Instance Metadata** (no explicit credentials)
193-
194-
- **Azure DNS**:
195-
- ✅ **Client Secret** (explicit `TenantId`, `ClientId`, `ClientSecret`)
196-
- ✅ **Managed Identity** or environment-based credentials via `DefaultAzureCredential`
197-
198-
- **Cloudflare**:
199-
- ✅ **Bearer API Token** for zone-level DNS control
200-
201-
- **NS1**:
202-
- ✅ **API Key** passed in header `X-NSONE-Key`
203-
204-
- **Infoblox**:
205-
- ✅ **Username/Password** (Basic Auth via WAPI REST API)
206-
- Optional: `Infoblox_WapiVersion` (defaults to `2.12`)
207-
- Optional: `Infoblox_IgnoreSslErrors` for self-signed certificates
208-
209-
- **RFC 2136 (BIND)**:
210-
- ✅ **TSIG Key** for secure dynamic DNS updates
211-
- Supports algorithms: `hmac-md5`, `hmac-sha1`, `hmac-sha256`, `hmac-sha384`, `hmac-sha512`
212-
- Default algorithm: `hmac-sha256` (recommended)
213-
- Optional: `Rfc2136_Port` (defaults to `53`)
178+
Authentication methods and required configuration keys are specific to each DNS provider and are **documented in that provider's own plugin repository** — see the [`-dnsplugin` repositories](https://github.com/orgs/Keyfactor/repositories?q=-dnsplugin). Credentials and settings are supplied through the AnyCA Gateway's **Domain Validation** configuration for the chosen plugin, not in this ACME plugin's configuration.
214179

215180
</details>
216181

217182
<details>
218-
<summary><strong>🏢 On-Premise DNS (RFC 2136)</strong></summary>
219-
220-
The RFC 2136 provider enables ACME DNS-01 challenges with on-premise DNS servers that support dynamic updates, including:
221-
222-
- **BIND** (Berkeley Internet Name Domain)
223-
- **PowerDNS** (with dynamic update support)
224-
- Any DNS server supporting RFC 2136 with TSIG authentication
225-
226-
#### Configuration Requirements
183+
<summary><strong>🏢 On-Premise / Private DNS</strong></summary>
227184

228-
| Field | Description | Required |
229-
|-------|-------------|----------|
230-
| `Rfc2136_Server` | DNS server hostname or IP address | ✅ Yes |
231-
| `Rfc2136_Zone` | DNS zone to update (e.g., `example.com`) | ✅ Yes |
232-
| `Rfc2136_TsigKeyName` | TSIG key name (e.g., `acme-update-key`) | ✅ Yes |
233-
| `Rfc2136_TsigKey` | Base64-encoded TSIG secret key | ✅ Yes |
234-
| `Rfc2136_TsigAlgorithm` | TSIG algorithm (default: `hmac-sha256`) | Optional |
235-
| `Rfc2136_Port` | DNS server port (default: `53`) | Optional |
236-
| `DnsVerificationServer` | DNS server IP for verification (for private zones) | Optional |
185+
On-premise and private DNS support (e.g. RFC 2136 dynamic updates against BIND/PowerDNS with TSIG) is provided by the corresponding DNS provider plugin — see its repository under the [`-dnsplugin` list](https://github.com/orgs/Keyfactor/repositories?q=-dnsplugin) for TSIG key generation, server/zone settings, and setup examples.
237186

238-
#### Generating TSIG Keys
239-
240-
**For BIND:**
241-
bash
242-
243-
**Generate a TSIG key using tsig-keygen (BIND 9.10+)**
244-
tsig-keygen -a hmac-sha256 acme-update-key
245-
246-
**Output example:**
247-
key "acme-update-key" {
248-
algorithm hmac-sha256;
249-
secret "base64encodedkey==";
250-
};
251-
252-
#### BIND Configuration Example
253-
254-
Add to `named.conf`:
255-
256-
key "acme-update-key" {
257-
algorithm hmac-sha256;
258-
secret "YourBase64EncodedKeyHere==";
259-
};
260-
261-
zone "example.com" {
262-
type master;
263-
file "/var/named/example.com.zone";
264-
allow-update { key "acme-update-key"; };
265-
};
266-
267-
268-
> ⚠️ **Security Note:** TSIG keys should be treated as secrets. Store them securely and use strong keys generated with cryptographically secure random number generators.
269-
270-
> ⚠️ **Private DNS Zones:** For private/local DNS zones (e.g., `.local`), set `DnsVerificationServer` to your authoritative DNS server IP so the plugin can verify TXT record propagation.
187+
> ⚠️ **Private DNS Zones:** For private/local DNS zones (e.g., `.local`) that are not reachable via public resolvers, set `DnsVerificationServer` to your authoritative DNS server IP. This ACME plugin uses it both to verify TXT record propagation and to resolve CNAME delegation chains.
271188
272189
</details>
273190

274191
<details>
275192
<summary><strong>🧩 Adding New DNS Providers</strong></summary>
276193

277-
To add support for new DNS services:
278-
279-
1. Implement the `IDnsProvider` interface:
280-
```csharp
281-
public interface IDnsProvider
282-
{
283-
Task<bool> CreateRecordAsync(string recordName, string txtValue);
284-
Task<bool> DeleteRecordAsync(string recordName);
285-
}
286-
```
287-
288-
2. Register the new provider in the `DnsProviderFactory`:
289-
```csharp
290-
case "yourprovider":
291-
return new YourCustomDnsProvider(config.YourProviderConfigValues...);
292-
```
194+
DNS providers are independent plugins, so adding a new one requires **no change to this ACME plugin**. Publish a plugin that implements the AnyCA Gateway's `IDomainValidator` interface (create/cleanup the validation record for a domain), deploy it alongside the Gateway, and configure it under **Domain Validation**. The Gateway will resolve it per domain at enrollment time.
293195

294-
3. Use zone detection logic similar to `GoogleDnsProvider`, `AzureDnsProvider`, or `Ns1DnsProvider`.
295-
296-
Each provider is instantiated dynamically based on the `DnsProvider` field in the `AcmeClientConfig`.
297-
298-
> 🔁 This modular DNS system ensures challenge automation works across cloud providers and is easily extensible.
196+
Use any existing plugin in the [`-dnsplugin` list](https://github.com/orgs/Keyfactor/repositories?q=-dnsplugin) as a reference implementation.
299197

300198
</details>
301199

302200
<details>
303-
<summary><strong>🔒 CA-Level DNS Provider Binding</strong></summary>
201+
<summary><strong>🔒 Per-Domain DNS Provider Resolution</strong></summary>
304202

305-
Each ACME/DNS combination is supported **at the CA level**, meaning that only **one DNS provider** is configured per CA entry in Keyfactor. This ensures a clear and isolated challenge path for each ACME CA connector instance.
306-
307-
If you need to support multiple DNS zones/providers (e.g., both AWS and Cloudflare), configure **separate CA entries**, each with its own DNS provider configuration.
203+
You can configure **multiple DNS provider plugins** and the Gateway selects the appropriate one for each domain based on your **Domain Validation** configuration (matching a configured, optionally wildcard, domain pattern). This also means a single certificate with SANs across different zones/providers can be validated using different plugins, and CNAME-delegated challenges are routed to the plugin that owns the delegation target's zone (see **CNAME Delegation** above).
308204

309205
</details>
310206

@@ -576,13 +472,9 @@ If `AccountStoragePath` is not set and `%APPDATA%` is unavailable, the plugin de
576472
</details>
577473

578474
<details>
579-
<summary><strong>🌐 Google Cloud DNS in Containers</strong></summary>
580-
581-
For Google Cloud DNS in container environments, you have three authentication options:
475+
<summary><strong>🌐 DNS Provider Authentication in Containers</strong></summary>
582476

583-
1. **Workload Identity (GKE)**: No explicit credentials needed; uses pod identity.
584-
2. **JSON key in config**: Paste the service account JSON directly into `Google_ServiceAccountKeyJson`.
585-
3. **Mounted JSON file**: Mount the service account key file and set `Google_ServiceAccountKeyPath`.
477+
DNS provider credentials in containerized environments are handled by each **DNS provider plugin**, not by this ACME plugin. Options such as cloud-native identity (GKE Workload Identity, EKS IRSA, AKS Pod Identity), mounted key files, or config-supplied secrets depend on the provider — see the relevant plugin under the [`-dnsplugin` list](https://github.com/orgs/Keyfactor/repositories?q=-dnsplugin) for its supported container authentication methods.
586478

587479
</details>
588480

0 commit comments

Comments
 (0)