certbot-dns-oraclecloud

A Certbot authenticator for completing DNS-01 challenges in public Oracle Cloud Infrastructure (OCI) DNS zones.

The plugin supports API-key, instance-principal, and resource-principal authentication. It discovers the most-specific matching public OCI DNS zone, adds the exact TXT value required by Certbot, and removes only that value during cleanup. Private DNS zones are intentionally unsupported because they cannot satisfy public ACME validation.

This project is not a drop-in replacement for certbot-dns-oci; its configuration and command-line contract are intentionally different.

Installation

Python 3.10 or newer is required. Install Certbot and the plugin together with uv:

uv tool install --with certbot-dns-oraclecloud certbot

Confirm that Certbot can discover the authenticator:

certbot plugins --text | grep dns-oraclecloud

Quick start

1. Configure an OCI API-key profile with permission to read public DNS zones and manage their records.

2. Install Certbot with the plugin and verify discovery:

   uv tool install --with certbot-dns-oraclecloud certbot
   certbot plugins --text | grep dns-oraclecloud
   

3. Request a certificate using that profile:

   certbot certonly --authenticator dns-oraclecloud \
     --dns-oraclecloud-auth-type api_key \
     --dns-oraclecloud-credentials ~/.oci/config \
     --dns-oraclecloud-profile CERTBOT \
     --dns-oraclecloud-propagation-seconds 60 \
     -d example.com
   

Usage

API-key authentication

api_key is the default authentication mode. The credentials file defaults to ~/.oci/config, and the profile defaults to DEFAULT:

certbot certonly --authenticator dns-oraclecloud \
  --dns-oraclecloud-auth-type api_key \
  --dns-oraclecloud-credentials ~/.oci/config \
  --dns-oraclecloud-profile CERTBOT \
  -d example.com

Instance-principal authentication

Run Certbot on an OCI compute instance whose dynamic group has the required DNS permissions. The authenticator reads the configured credentials and profile values before selecting this mode, but the instance-principal client factory does not use them:

certbot certonly --authenticator dns-oraclecloud \
  --dns-oraclecloud-auth-type instance_principal \
  -d example.com

Resource-principal authentication

Run Certbot in an OCI resource environment that supplies a resource-principal signer:

certbot certonly --authenticator dns-oraclecloud \
  --dns-oraclecloud-auth-type resource_principal \
  -d example.com

Authentication selection is explicit. A failed principal mode does not fall back to another principal or to an API key.

Plugin options

Documentation

The project documentation covers installation, authentication, least-privilege OCI IAM policies, development, and releases.

Contributing

See CONTRIBUTING.md for guidelines.

Security issues should be reported privately as described in SECURITY.md.

License

This project is licensed under the Universal Permissive License 1.0.