Skip to content

Certificate Authority Role

The certificate_authority role issues and manages X.509 certificates for Windows and Linux hosts. Two dimensions determine which tags to use: the signing back-end (who signs the CSR) and the target OS (where the certificate ends up).

Use Cases

Ansible Internal CA → Windows target

Use when there is no existing PKI and the certificate needs to live in a Windows machine store (e.g. for IIS). The role manages its own self-signed CA, signs the CSR on the control node, and imports the result on the Windows host.

Tags: generate_csr_windows, sign_certificate, import_certificate_windows Docs: Ansible Internal CA

Ansible Internal CA → Linux target

Use when there is no existing PKI and the certificate needs to be written as PEM files on a Linux host (e.g. for nginx or another TLS-capable service). The role generates a key and CSR on the Linux target, signs on the control node, and writes the cert and key to configurable paths.

Tags: generate_key_linux, generate_csr_linux, sign_certificate, write_certificate_linux Docs: Linux Hosts

Microsoft CA → Windows target (direct)

Use when an Active Directory Enterprise CA is already in place and the target host is domain-joined. The role submits a CSR via certreq.exe directly from the target and imports the signed result. No CA management or trust distribution is needed.

Tags: generate_csr_windows, sign_certificate_microsoft_ca, import_certificate_windows Docs: Microsoft AD Integrated CA

Microsoft CA → Windows target (via delegate host)

Use when only one Windows host has enrollment permissions against the CA. Set certificate_authority_delegate_host to that host — the CSR, signing, and PFX export all run there, and deploy_certificate_windows copies the result to each inventory target. Always use --forks=1 to prevent concurrent certreq.exe operations on the delegate.

Tags: generate_csr_windows, sign_certificate_microsoft_ca, import_certificate_windows, export_certificate_windows, deploy_certificate_windows Docs: Microsoft AD Integrated CA — Deploying via a delegate host

Microsoft CA → Linux target (via Windows delegate)

Use when a Microsoft CA must sign the certificate but the certificate needs to be deployed to a Linux host. A Windows delegate handles enrollment and PFX export; the role then extracts the cert and key from the PFX on the control node and pushes them to the Linux target as PEM files.

Tags: generate_csr_windows, sign_certificate_microsoft_ca, import_certificate_windows, export_certificate_windows, deploy_certificate_linux Docs: Linux Hosts — Deploying via a Windows delegate host

Choosing a signing back-end

No existing PKI Active Directory Enterprise CA
Windows target Ansible Internal CA Microsoft AD Integrated CA
Linux target Ansible Internal CA → Linux Microsoft CA via delegate → Linux

Workflow Quick Reference

Feature Playbook / Role Type Status Notes
Generate Ansible root CA certificate_authority setup prod --tags generate_ca
Trust Ansible CA on Windows certificate_authority trust prod --tags trust_root_ca_windows
Issue cert — Ansible CA → Windows playbooks/certificate-authority-issue.yml issue prod --tags generate_csr_windows,sign_certificate,import_certificate_windows
Issue cert — Ansible CA → Linux playbooks/certificate-authority-issue.yml issue prod --tags generate_key_linux,generate_csr_linux,sign_certificate,write_certificate_linux
Issue cert — Microsoft CA → Windows (direct) playbooks/certificate-authority-issue.yml issue prod --tags generate_csr_windows,sign_certificate_microsoft_ca,import_certificate_windows
Issue cert — Microsoft CA → Windows (delegate) playbooks/certificate-authority-issue.yml issue prod --tags generate_csr_windows,sign_certificate_microsoft_ca,import_certificate_windows,export_certificate_windows,deploy_certificate_windows --forks=1
Issue cert — Microsoft CA → Linux (via Windows delegate) playbooks/certificate-authority-issue.yml issue prod --tags generate_csr_windows,sign_certificate_microsoft_ca,import_certificate_windows,export_certificate_windows,deploy_certificate_linux --forks=1
Renew cert only — Linux (reuse existing key) playbooks/certificate-authority-issue.yml renew prod --tags generate_csr_linux,sign_certificate,write_certificate_linux certificate_authority_linux_reuse_key: true
Import existing PFX — Windows certificate_authority deploy prod --tags import_pfx_windows
Install IIS certificate_authority install prod --tags install_iis
Bind certificate to IIS site certificate_authority bind prod --tags bind_iis_certificate
Deploy PFX from Windows delegate → Linux certificate_authority deploy prod --tags deploy_certificate_linux

Generating the Root CA

The Ansible internal CA flow depends on a root CA that the role generates and stores in an encrypted Ansible Vault file. The CA's private key is created in memory and is never written to disk in cleartext — it is encrypted before the file is ever opened. The vault file is portable: you can generate the CA in one environment (e.g. a security-controlled workstation) and ship the encrypted file to wherever it will be used.

See Generating the Ansible Root CA for the security model, the variables that control it, and the recommended cross-environment workflow.

The Microsoft AD integrated flow does not need this step; it submits CSRs to an existing Enterprise CA.

Tag Reference

Tag Use case Description
generate_ca Ansible CA Generate a new self-signed CA and save it to an encrypted vault file
trust_root_ca_windows Ansible CA Install the Ansible CA into the Windows Trusted Root store
sign_certificate Ansible CA Sign a CSR with the Ansible-managed CA on the control node
generate_csr_windows Windows — Both Generate a CSR on a Windows host using certreq.exe -new
sign_certificate_microsoft_ca Windows — Microsoft CA Submit a CSR to a Microsoft CA via certreq.exe -submit
import_certificate_windows Windows — Both Import a signed certificate on a Windows host via certreq.exe -accept
export_certificate_windows Windows — Both Export an imported certificate from the Windows machine store as a PFX file
deploy_certificate_windows Windows — Both Copy an exported PFX from a Windows delegate host to a Windows target and import it
deploy_certificate_linux Linux — Both Copy an exported PFX from a Windows delegate host to a Linux target, extract cert and key, and write them to disk
import_pfx_windows Windows — Both Import a PFX file that already exists on the Windows host into LocalMachine\My
install_iis Windows — Both Install the IIS web server Windows feature
bind_iis_certificate Windows — Both Bind an issued certificate to an IIS web site
generate_key_linux Linux — Ansible CA Generate an RSA or ECC private key on a Linux host
generate_csr_linux Linux — Ansible CA Generate a CSR on a Linux host
write_certificate_linux Linux — Ansible CA Write the signed certificate to a file on a Linux host

No tasks run unless a tag is explicitly specified — see the use case pages for the supported tag combinations and ordering.

Requirements

  1. The community.crypto Ansible collection must be installed on the control node.
  2. The ansible.windows collection must be installed for Windows tasks.
  3. Python's cryptography package must be available on the control node (pip install cryptography).
  4. For Linux targets: the python3-cryptography OS package must be installed on the target host. The generate_key_linux and generate_csr_linux tasks install it automatically via the OS package manager.

Fact Gathering

The role works whether gather_facts is on or off:

  • With facts on (the default), the role enriches default DNS SANs with ansible_fqdn/ansible_hostname and can auto-derive the IP SAN from ansible_ip_addresses when certificate_authority_cert_include_ip_san: true.
  • With facts off, default DNS SANs fall back to inventory_hostname/inventory_hostname_short. For an IP SAN, add an explicit "IP:<addr>" entry to certificate_authority_cert_sans instead of relying on auto-detection.