Chapter 22. Managing IdM certificates using Ansible
You can use the ansible-freeipa
ipacert
module to request, revoke, and retrieve SSL certificates for Identity Management (IdM) users, hosts and services. You can also restore a certificate that has been put on hold.
22.1. Using Ansible to request SSL certificates for IdM hosts, services and users
You can use the ansible-freeipa
ipacert
module to request SSL certificates for Identity Management (IdM) users, hosts and services. They can then use these certificates to authenticate to IdM.
Complete this procedure to request a certificate for an HTTP server from an IdM certificate authority (CA) using an Ansible playbook.
Prerequisites
On the control node:
- You are using Ansible version 2.14 or later.
-
You have installed the
ansible-freeipa
package. - You have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server in the ~/MyPlaybooks/ directory.
-
You have stored your
ipaadmin_password
in the secret.yml Ansible vault.
- Your IdM deployment has an integrated CA.
Procedure
Generate a certificate-signing request (CSR) for your user, host or service. For example, to use the
openssl
utility to generate a CSR for theHTTP
service running on client.idm.example.com, enter:# openssl req -new -newkey rsa:2048 -days 365 -nodes -keyout new.key -out new.csr -subj '/CN=client.idm.example.com,O=IDM.EXAMPLE.COM'
As a result, the CSR is stored in new.csr.
Create your Ansible playbook file request-certificate.yml with the following content:
--- - name: Playbook to request a certificate hosts: ipaserver vars_files: - /home/user_name/MyPlaybooks/secret.yml tasks: - name: Request a certificate for a web server ipacert: ipaadmin_password: "{{ ipaadmin_password }}" state: requested csr: | -----BEGIN CERTIFICATE REQUEST----- MIGYMEwCAQAwGTEXMBUGA1UEAwwOZnJlZWlwYSBydWxlcyEwKjAFBgMrZXADIQBs HlqIr4b/XNK+K8QLJKIzfvuNK0buBhLz3LAzY7QDEqAAMAUGAytlcANBAF4oSCbA 5aIPukCidnZJdr491G4LBE+URecYXsPknwYb+V+ONnf5ycZHyaFv+jkUBFGFeDgU SYaXm/gF8cDYjQI= -----END CERTIFICATE REQUEST----- principal: HTTP/client.idm.example.com register: cert
Replace the certificate request with the CSR from new.csr.
Request the certificate:
$ ansible-playbook --vault-password-file=password_file -v -i <path_to_inventory_directory>/hosts <path_to_playbooks_directory>/request-certificate.yml
Additional resources
22.2. Using Ansible to revoke SSL certificates for IdM hosts, services and users
You can use the ansible-freeipa
ipacert
module to revoke SSL certificates used by Identity Management (IdM) users, hosts and services to authenticate to IdM.
Complete this procedure to revoke a certificate for an HTTP server using an Ansible playbook. The reason for revoking the certificate is “keyCompromise”.
Prerequisites
On the control node:
- You are using Ansible version 2.14 or later.
-
You have installed the
ansible-freeipa
package. - You have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server in the ~/MyPlaybooks/ directory.
-
You have stored your
ipaadmin_password
in the secret.yml Ansible vault. -
You have obtained the serial number of the certificate, for example by entering the
openssl x509 -noout -text -in <path_to_certificate>
command. In this example, the serial number of the certificate is 123456789.
- Your IdM deployment has an integrated CA.
Procedure
Create your Ansible playbook file revoke-certificate.yml with the following content:
--- - name: Playbook to revoke a certificate hosts: ipaserver vars_files: - /home/user_name/MyPlaybooks/secret.yml tasks: - name: Revoke a certificate for a web server ipacert: ipaadmin_password: "{{ ipaadmin_password }}" serial_number: 123456789 revocation_reason: "keyCompromise" state: revoked
Revoke the certificate:
$ ansible-playbook --vault-password-file=password_file -v -i <path_to_inventory_directory>/hosts <path_to_playbooks_directory>/revoke-certificate.yml
Additional resources
22.3. Using Ansible to restore SSL certificates for IdM users, hosts, and services
You can use the ansible-freeipa
ipacert
module to restore a revoked SSL certificate previously used by an Identity Management (IdM) user, host or a service to authenticate to IdM.
You can only restore a certificate that was put on hold. You may have put it on hold because, for example, you were not sure if the private key had been lost. However, now you have recovered the key and as you are certain that no-one has accessed it in the meantime, you want to reinstate the certificate.
Complete this procedure to use an Ansible playbook to release a certificate for a service enrolled into IdM from hold. This example describes how to release a certificate for an HTTP service from hold.
Prerequisites
On the control node:
- You are using Ansible version 2.14 or later.
-
You have installed the
ansible-freeipa
package. - You have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server in the ~/MyPlaybooks/ directory.
-
You have stored your
ipaadmin_password
in the secret.yml Ansible vault.
- Your IdM deployment has an integrated CA.
-
You have obtained the serial number of the certificate, for example by entering the
openssl x509 -noout -text -in path/to/certificate
command. In this example, the certificate serial number is 123456789.
Procedure
Create your Ansible playbook file restore-certificate.yml with the following content:
--- - name: Playbook to restore a certificate hosts: ipaserver vars_files: - /home/user_name/MyPlaybooks/secret.yml tasks: - name: Restore a certificate for a web service ipacert: ipaadmin_password: "{{ ipaadmin_password }}" serial_number: 123456789 state: released
Run the playbook:
$ ansible-playbook --vault-password-file=password_file -v -i <path_to_inventory_directory>/hosts <path_to_playbooks_directory>/restore-certificate.yml
Additional resources
22.4. Using Ansible to retrieve SSL certificates for IdM users, hosts, and services
You can use the ansible-freeipa
ipacert
module to retrieve an SSL certificate issued for an Identity Management (IdM) user, host or a service, and store it in a file on the managed node.
Prerequisites
On the control node:
- You are using Ansible version 2.14 or later.
-
You have installed the
ansible-freeipa
package. - You have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server in the ~/MyPlaybooks/ directory.
-
You have stored your
ipaadmin_password
in the secret.yml Ansible vault.
-
You have obtained the serial number of the certificate, for example by entering the
openssl x509 -noout -text -in <path_to_certificate>
command. In this example, the serial number of the certificate is 123456789, and the file in which you store the retrieved certificate is cert.pem.
Procedure
Create your Ansible playbook file retrieve-certificate.yml with the following content:
--- - name: Playbook to retrieve a certificate and store it locally on the managed node hosts: ipaserver vars_files: - /home/user_name/MyPlaybooks/secret.yml tasks: - name: Retrieve a certificate and save it to file 'cert.pem' ipacert: ipaadmin_password: "{{ ipaadmin_password }}" serial_number: 123456789 certificate_out: cert.pem state: retrieved
Retrieve the certificate:
$ ansible-playbook --vault-password-file=password_file -v -i <path_to_inventory_directory>/hosts <path_to_playbooks_directory>/retrieve-certificate.yml
Additional resources