DNS Provider Plugin Architecture

This document walks through the code-level integration between a Keyfactor CA Gateway plugin (e.g. the ACME CA plugin) and the DNS provider plugins that it delegates domain-control validation to. The AWS Route 53 DNS provider is used as the concrete example, but every provider plugin (Azure DNS, Cloudflare, NS1, RFC 2136, Infoblox, Google Cloud DNS) follows the same contract.

1. Architectural Overview

The CA Gateway plugin never talks to a DNS provider’s SDK directly. Instead, it depends on a small set of interfaces from Keyfactor.AnyGateway.IAnyCAPlugin that let the gateway runtime resolve the correct provider at runtime — per-domain — based on whatever provider DLLs have been dropped into the gateway’s extension folder.

1. Resolve — the CA plugin calls factory.ResolveDomainValidator(domain, challengeType).
2. Dispatch — the gateway returns the IDomainValidator implementation matching the domain’s zone.
3. Work — the CA plugin calls StageValidation() / CleanupValidation() on the validator.
4. Return — the validator returns a DomainValidationResult { Success, ErrorMessage }.

2. The Contract

Three interfaces — all shipped in the Keyfactor.AnyGateway.IAnyCAPlugin NuGet package — define the entire relationship:

DomainValidationResult

The return shape is intentionally small:

public class DomainValidationResult
{
    public bool Success { get; set; }
    public string ErrorMessage { get; set; }
}

3. The CA Plugin Side (Caller)

The CA plugin receives an IDomainValidatorFactory through constructor injection, then resolves a validator per-domain during enrollment.

3.1 — Constructor injection

public class AcmeCaPlugin : IAnyCAPlugin
{
    private readonly IDomainValidatorFactory _validatorFactory;

    public AcmeCaPlugin(IDomainValidatorFactory validatorFactory)
    {
        _validatorFactory = validatorFactory ?? throw new ArgumentNullException(nameof(validatorFactory),
            "IDomainValidatorFactory is required. DNS providers are externalized as plugins.");
    }
}

3.2 — Resolving the validator per-domain

var domain = authz.Identifier.Value;

var domainValidator = _validatorFactory.ResolveDomainValidator(domain, DNS_CHALLENGE_TYPE);
if (domainValidator == null)
{
    throw new InvalidOperationException(
        $"Failed to resolve domain validator for domain '{domain}'. " +
        "Ensure the appropriate DNS provider plugin is deployed and configured.");
}

// Stage the DNS TXT record through whichever provider the gateway selected
var result = await domainValidator.StageValidation(
    validation.DnsRecordName,       // e.g. "_acme-challenge.example.com"
    validation.DnsRecordValue,      // the ACME-provided challenge token
    CancellationToken.None);

if (!result.Success)
    throw new InvalidOperationException(
        $"Failed to stage DNS validation for {domain}: {result.ErrorMessage}");

3.3 — Cleanup

Regardless of whether the challenge succeeded, the CA plugin calls CleanupValidation on each validator it used, so temporary TXT records don’t linger in the customer’s zone.

foreach (var (authz, challenge, validation, validator) in pendingChallenges)
{
    try
    {
        await validator.CleanupValidation(validation.DnsRecordName, CancellationToken.None);
    }
    catch (Exception ex)
    {
        _logger.LogWarning(ex, "Failed to cleanup DNS record for {Domain}", domain);
        // Continue cleanup for other domains even if one fails
    }
}

4. The DNS Provider Plugin Side (AWS Route 53 Example)

A DNS provider plugin is a standalone .NET project that produces a single DLL plus a manifest.json. No code in the CA plugin needs to change to add a new provider.

4.1 — Project layout

aws-route53-dnsplugin/
├── Keyfactor.DnsProvider.AwsRoute53/
│   ├── AwsRoute53DomainValidator.cs      // implements IDomainValidator
│   ├── AwsRoute53DnsProvider.cs          // wraps AWSSDK.Route53
│   └── Keyfactor.DnsProvider.AwsRoute53.csproj
├── manifest.json
└── integration-manifest.json

4.2 — The validator class

using Keyfactor.AnyGateway.Extensions;

namespace Keyfactor.Extensions.DomainValidator.AwsRoute53
{
    public class AwsRoute53DomainValidator : IDomainValidator
    {
        private AwsRoute53DnsProvider _provider;
        private Dictionary<string, object> _configuration;

        public void Initialize(IDomainValidatorConfigProvider configProvider)
        {
            _configuration = configProvider.DomainValidationConfiguration;

            string accessKey = GetConfigValue("AwsRoute53_AccessKey");
            string secretKey = GetConfigValue("AwsRoute53_SecretKey");

            _provider = new AwsRoute53DnsProvider(accessKey, secretKey);
        }

        public async Task<DomainValidationResult> StageValidation(
            string key, string value, CancellationToken cancellationToken)
        {
            try
            {
                var success = await _provider.CreateRecordAsync(key, value);
                return new DomainValidationResult
                {
                    Success = success,
                    ErrorMessage = success ? null : $"Failed to create TXT record for {key}"
                };
            }
            catch (Exception ex)
            {
                return new DomainValidationResult
                {
                    Success = false,
                    ErrorMessage = $"Failed to create TXT record: {ex.Message}"
                };
            }
        }

        public async Task<DomainValidationResult> CleanupValidation(
            string key, CancellationToken cancellationToken)
        {
            var success = await _provider.DeleteRecordAsync(key);
            return new DomainValidationResult
            {
                Success = success,
                ErrorMessage = success ? null : $"Failed to delete TXT record for {key}"
            };
        }
    }
}

4.3 — The actual AWS SDK call (the only provider-specific bit)

var request = new ChangeResourceRecordSetsRequest
{
    HostedZoneId = zone.Id,
    ChangeBatch = new ChangeBatch
    {
        Changes = new List<Change>
        {
            new Change
            {
                Action = ChangeAction.UPSERT,
                ResourceRecordSet = new ResourceRecordSet
                {
                    Name = EnsureTrailingDot(recordName),
                    Type = RRType.TXT,
                    TTL = 60,
                    ResourceRecords = new List<ResourceRecord>
                    {
                        new ResourceRecord { Value = $"\"{txtValue}\"" }
                    }
                }
            }
        }
    }
};

var response = await _route53Client.ChangeResourceRecordSetsAsync(request);

4.4 — Declaring configurable properties

Each plugin declares its configuration surface so the gateway can render the fields in the Command UI:

public Dictionary<string, PropertyConfigInfo> GetDomainValidatorAnnotations()
{
    return new Dictionary<string, PropertyConfigInfo>
    {
        ["AwsRoute53_AccessKey"] = new PropertyConfigInfo
        {
            Comments = "AWS Route53: Access Key ID (Optional if using IAM role)",
            Hidden = false,
            DefaultValue = "",
            Type = "Secret"
        },
        ["AwsRoute53_SecretKey"] = new PropertyConfigInfo
        {
            Comments = "AWS Route53: Secret Access Key (Optional if using IAM role)",
            Hidden = true,
            DefaultValue = "",
            Type = "Secret"
        }
    };
}

5. Discovery: manifest.json

The gateway discovers plugins by scanning its extension folder for manifest.json files. Each manifest names the plugin’s assembly, its implementation type, and its provider key — everything the gateway needs to load the DLL by reflection and register it with the factory.

{
  "pluginType":       "DomainValidator",
  "validationType":   "DNS",
  "providerName":     "awsroute53",
  "displayName":      "AWS Route53 DNS",
  "description":      "DNS-01 challenge validation using AWS Route53",
  "assemblyName":     "AwsRoute53DomainValidator.dll",
  "typeName":         "Keyfactor.Extensions.DomainValidator.AwsRoute53.AwsRoute53DomainValidator",
  "version":          "1.0.0",
  "author":           "Keyfactor",
  "configurationFields": [
    "AwsRoute53_AccessKey",
    "AwsRoute53_SecretKey"
  ]
}

csproj wiring so the manifest ships with the DLL

<ItemGroup>
  <PackageReference Include="Keyfactor.AnyGateway.IAnyCAPlugin" Version="3.3.0-PRERELEASE-..." />
  <PackageReference Include="AWSSDK.Core"    Version="4.0.3.11" />
  <PackageReference Include="AWSSDK.Route53" Version="4.0.8.8" />
  <None Update="manifest.json">
    <CopyToOutputDirectory>Always</CopyToOutputDirectory>
  </None>
</ItemGroup>

6. End-to-End Sequence

A full happy-path enrollment that spans a Route 53 domain and an Infoblox domain:

7. Why This Shape

• CA-agnostic: any CA Gateway plugin (ACME, DigiCert, etc.) that needs DNS validation uses the exact same three interfaces. Replacing the ACME plugin with a DigiCert plugin does not require rebuilding any DNS provider.
• Minimum surface area per provider: a DNS plugin only has to deal with one thing — creating and deleting a TXT record. No awareness of the ACME protocol, no awareness of the CA plugin, no awareness of the gateway’s lifecycle.
• Independent deployment: a bugfix in the Route 53 plugin ships as a single DLL. Customers upgrade only the providers they actually use.
• Credentials stay isolated: AWS keys live in the Route 53 plugin’s config scope; they are never visible to the CA plugin or to other DNS provider plugins.

8. Building a New DNS Provider — Checklist

1. New .NET class library project targeting the same TFM as the gateway.
2. Reference Keyfactor.AnyGateway.IAnyCAPlugin.
3. Implement IDomainValidator — Initialize, StageValidation, CleanupValidation, GetValidationType, GetDomainValidatorAnnotations, ValidateConfiguration.
4. Add a manifest.json with pluginType: "DomainValidator", a unique providerName, the assemblyName, and the fully-qualified typeName.
5. Mark manifest.json as CopyToOutputDirectory: Always in the csproj.
6. Build — drop the output DLL + manifest into the gateway’s extension folder — restart the gateway.
7. Configure the plugin’s fields in the Command UI — the annotations you returned from GetDomainValidatorAnnotations become the form schema.