linux-system-roles.certificate

Certificate System Role

This role helps manage the issuance and renewal of TLS/SSL certificates.

Basic Usage:

---
- hosts: webserver

  vars:
    certificate_requests:
      - name: mycert
        dns: www.example.com
        ca: self-sign

  roles:
    - linux-system-roles.certificate

When used in an RPM-based system, the certificate will be saved at /etc/pki/tls/certs/mycert.crt and the key will be saved at /etc/pki/tls/private/mycert.key.

Requirements

Collection Requirements

This role needs external collections only for managing rpm-ostree nodes. You can install the required collections with this command:

ansible-galaxy collection install -vv -r meta/collection-requirements.yml

Variables

Parameter	Description	Type	Required	Default
certificate_wait	Should the task wait for the certificate to be issued?	bool	no	yes
certificate_requests	A list of dictionaries, each representing a certificate request.	list	no	-

certificate_requests

Note: Some fields in the certificate request follow RFC 5280, like common_name, country, state, locality, organization, etc.

Note: The CA may not support all requested fields. For instance, requesting country: US might not result in the country field being included in the certificate.

Note: Fields like dns, email, and ip are used for Subject Alternative Names (SAN).

Parameter	Description	Type	Required	Default
name	The name of the certificate, including its directory path for storage.	str	yes	-
ca	The Certificate Authority that will issue the certificate.	str	yes	-
dns	The domain(s) to be included in the certificate.	str or list	no	-
email	The email(s) to be included in the certificate.	str or list	no	-
ip	The IP(s) to be included in the certificate.	str or list	no	-
auto_renew	Should the certificate be renewed automatically before expiration?	bool	no	yes
owner	The user name or ID for the certificate and key files.	str	no	User running Ansible
group	The group name or ID for the certificate and key files.	str	no	Group running Ansible
mode	Permissions for the certificate and key files.	raw	no	-
key_size	Key size in bits for the certificate.	int	no	2048
common_name	The common name for the certificate subject.	str	no	See [common_name]
country	Country code for the certificate subject.	str	no	-
state	State for the certificate subject.	str	no	-
locality	Locality (often city) for the certificate subject.	str	no	-
organization	Organization for the certificate subject.	str	no	-
organizational_unit	Organizational unit for the certificate subject.	str	no	-
contact_email	Contact email for the certificate subject.	str	no	-
key_usage	Allowed key usages for the certificate.	list	no	See [key_usage]
extended_key_usage	Extended key usage attributes for the certificate request.	list	no	See [extended_key_usage]
run_before	Command to run before saving the certificate.	str	no	-
run_after	Command to run after saving the certificate.	str	no	-
principal	Kerberos principal.	str	no	-
provider	The method used to request and manage the certificate.	str	no	Varies by CA

CAs and Providers

CA	Providers	Description	Requirements
self-sign	certmonger*	Issue self-signed certificates.
ipa	certmonger*	Issue certificates using the FreeIPA CA.	Host needs to be enrolled in FreeIPA.

*Default provider.

Examples

Issuing a Self-Signed Certificate

To create a self-signed certificate:

---
- hosts: webserver

  vars:
    certificate_requests:
      - name: mycert
        dns: *.example.com
        ca: self-sign

  roles:
    - linux-system-roles.certificate

Specifying Certificate Storage Path

To specify where to save the certificate and key:

---
- hosts: webserver
  vars:
    certificate_requests:
      - name: /another/path/mycert
        dns: *.example.com
        ca: self-sign

  roles:
    - linux-system-roles.certificate

Issuing Certificates with Multiple DNS, IP, and Email

To request multiple DNS and IP addresses:

---
- hosts: webserver
  vars:
    certificate_requests:
      - name: mycert
        dns:
          - www.example.com
          - sub1.example.com
        ip:
          - 192.0.2.12
        email:
          - [email protected]
        ca: self-sign

  roles:
    - linux-system-roles.certificate

Common Subject Options

To set common subject details:

---
- hosts: webserver
  vars:
    certificate_requests:
      - name: mycert
        dns: www.example.com
        common_name: www.example.com
        ca: self-sign
        country: US
        state: NY
        locality: New York
        organization: Example Org
        email: [email protected]

  roles:
    - linux-system-roles.certificate

Adjusting Key Size

To specify the key size:

---
- hosts: webserver
  vars:
    certificate_requests:
      - name: mycert
        dns: www.example.com
        ca: self-sign
        key_size: 4096

  roles:
    - linux-system-roles.certificate

Key Usage and Extended Key Usage

To set usage types:

---
- hosts: webserver
  vars:
    certificate_requests:
      - name: mycert
        dns: www.example.com
        ca: self-sign
        key_usage:
          - digitalSignature
        extended_key_usage:
          - id-kp-clientAuth
          
  roles:
    - linux-system-roles.certificate

Running Commands Before or After Issuance

To run commands around certificate issuance:

---
- hosts: webserver
  vars:
    certificate_requests:
      - name: mycert
        dns: www.example.com
        ca: self-sign
        run_before: systemctl stop myservice
        run_after: systemctl start myservice

  roles:
    - linux-system-roles.certificate