Chapter 51. Requesting certificates using RHEL System Roles

With the Certificate System Role, you can use Red Hat Ansible Engine to issue and manage certificates.

This chapter covers the following topics:

51.1. The Certificate System Role

Using the Certificate System Role, you can manage issuing and renewing TLS and SSL certificates using Red Hat Ansible Engine.

The role uses certmonger as the certificate provider, and currently supports issuing and renewing self-signed certificates and using the IdM integrated certificate authority (CA).

You can use the following variables in your Ansible playbook with the Certificate System Role:

  • certificate_wait to specify if the task should wait for the certificate to be issued.
  • certificate_requests to represent each certificate to be issued and its parameters.

Additional resources

  • For details about the parameters used in the certificate_requests variable and additional information about the certificate System Role, see the /usr/share/ansible/roles/rhel-system-roles.certificate/README.md file.
  • For details about RHEL System Roles and how to apply them, see Getting started with RHEL System Roles.

51.2. Requesting a new self-signed certificate using the Certificate System Role

With the Certificate System Role, you can use Red Hat Ansible Engine to issue self-signed certificates.

This process uses the certmonger provider and requests the certificate through the getcert command.

Note

By default, certmonger automatically tries to renew the certificate before it expires. You can disable this by setting the auto_renew parameter in the Ansible playbook to no.

Prerequisites

  • You have Red Hat Ansible Engine installed on the system from which you want to run the playbook.

    Note

    You do not have to have Ansible installed on the systems on which you want to deploy the certificate solution.

  • You have the rhel-system-roles package installed on the system from which you want to run the playbook.

    For details about RHEL System Roles and how to apply them, see Getting started with RHEL System Roles.

Procedure

  1. Optional: Create an inventory file, for example inventory.file:

    $ touch inventory.file
  2. Open your inventory file and define the hosts on which you want to request the certificate, for example:

    [webserver]
    server.idm.example.com
  3. Create a playbook file, for example request-certificate.yml:

    • Set hosts to include the hosts on which you want to request the certificate, such as webserver.
    • Set the certificate_requests variable to include the following:

      • Set the name parameter to the desired name of the certificate, such as mycert.
      • Set the dns parameter to the domain to be included in the certificate, such as *.example.com.
      • Set the ca parameter to self-sign.
    • Set the rhel-system-roles.certificate role under roles.

      This is the playbook file for this example:

      ---
      - hosts: webserver
      
        vars:
          certificate_requests:
            - name: mycert
              dns: *.example.com
              ca: self-sign
      
        roles:
          - rhel-system-roles.certificate
  4. Save the file.
  5. Run the playbook:

    $ ansible-playbook -i inventory.file request-certificate.yml

Additional resources

  • For details about the parameters used in the certificate_requests variable and additional information about the certificate System Role, see the /usr/share/ansible/roles/rhel-system-roles.certificate/README.md file.
  • For details about the ansible-playbook command, see the ansible-playbook(1) man page.

51.3. Requesting a new certificate from IdM CA using the Certificate System Role

With the Certificate System Role, you can use Red Hat Ansible Engine to issue certificates while using an IdM server with an integrated certificate authority (CA). Therefore, you can efficiently and consistently manage the certificate trust chain for multiple systems when using IdM as the CA.

This process uses the certmonger provider and requests the certificate through the getcert command.

Note

By default, certmonger automatically tries to renew the certificate before it expires. You can disable this by setting the auto_renew parameter in the Ansible playbook to no.

Prerequisites

  • You have Red Hat Ansible Engine installed on the system from which you want to run the playbook.

    Note

    You do not have to have Ansible installed on the systems on which you want to deploy the certificate solution.

  • You have the rhel-system-roles package installed on the system from which you want to run the playbook.

    For details about RHEL System Roles and how to apply them, see Getting started with RHEL System Roles.

Procedure

  1. Optional: Create an inventory file, for example inventory.file:

    $ touch inventory.file
  2. Open your inventory file and define the hosts on which you want to request the certificate, for example:

    [webserver]
    server.idm.example.com
  3. Create a playbook file, for example request-certificate.yml:

    • Set hosts to include the hosts on which you want to request the certificate, such as webserver.
    • Set the certificate_requests variable to include the following:

      • Set the name parameter to the desired name of the certificate, such as mycert.
      • Set the dns parameter to the domain to be included in the certificate, such as www.example.com.
      • Set the principal parameter to specify the Kerberos principal, such as HTTP/www.example.com@EXAMPLE.COM.
      • Set the ca parameter to ipa.
    • Set the rhel-system-roles.certificate role under roles.

      This is the playbook file for this example:

      ---
      - hosts: webserver
        vars:
          certificate_requests:
            - name: mycert
              dns: www.example.com
              principal: HTTP/www.example.com@EXAMPLE.COM
              ca: ipa
      
        roles:
          - rhel-system-roles.certificate
  4. Save the file.
  5. Run the playbook:

    $ ansible-playbook -i inventory.file request-certificate.yml

Additional resources

  • For details about the parameters used in the certificate_requests variable and additional information about the certificate System Role, see the /usr/share/ansible/roles/rhel-system-roles.certificate/README.md file.
  • For details about the ansible-playbook command, see the ansible-playbook(1) man page.

51.4. Specifying commands to run before or after certificate issuance using the Certificate System Role

With the Certificate System Role, you can use Red Hat Ansible Engine to execute a command before and after a certificate is issued or renewed.

In the following example, the administrator ensures stopping the httpd service before a self-signed certificate for www.example.com is issued or renewed, and restarting it afterwards.

Note

By default, certmonger automatically tries to renew the certificate before it expires. You can disable this by setting the auto_renew parameter in the Ansible playbook to no.

Prerequisites

  • You have Red Hat Ansible Engine installed on the system from which you want to run the playbook.

    Note

    You do not have to have Ansible installed on the systems on which you want to deploy the certificate solution.

  • You have the rhel-system-roles package installed on the system from which you want to run the playbook.

    For details about RHEL System Roles and how to apply them, see Getting started with RHEL System Roles.

Procedure

  1. Optional: Create an inventory file, for example inventory.file:

    $ touch inventory.file
  2. Open your inventory file and define the hosts on which you want to request the certificate, for example:

    [webserver]
    server.idm.example.com
  3. Create a playbook file, for example request-certificate.yml:

    • Set hosts to include the hosts on which you want to request the certificate, such as webserver.
    • Set the certificate_requests variable to include the following:

      • Set the name parameter to the desired name of the certificate, such as mycert.
      • Set the dns parameter to the domain to be included in the certificate, such as www.example.com.
      • Set the ca parameter to the CA you want to use to issue the certificate, such as self-sign.
      • Set the run_before parameter to the command you want to execute before this certificate is issued or renewed, such as systemctl stop httpd.service.
      • Set the run_after parameter to the command you want to execute after this certificate is issued or renewed, such as systemctl start httpd.service.
    • Set the rhel-system-roles.certificate role under roles.

      This is the playbook file for this example:

      ---
      - hosts: webserver
        vars:
          certificate_requests:
            - name: mycert
              dns: www.example.com
              ca: self-sign
              run_before: systemctl stop httpd.service
              run_after: systemctl start httpd.service
      
        roles:
          - linux-system-roles.certificate
  4. Save the file.
  5. Run the playbook:

    $ ansible-playbook -i inventory.file request-certificate.yml

Additional resources

  • For details about the parameters used in the certificate_requests variable and additional information about the certificate System Role, see the /usr/share/ansible/roles/rhel-system-roles.certificate/README.md file.
  • For details about the ansible-playbook command, see the ansible-playbook(1) man page.