Cert module ============ Description ----------- The cert module makes it possible to request, revoke and retrieve SSL certificates for hosts, services and users. Features -------- * Certificate request * Certificate hold/release * Certificate revocation * Certificate retrieval Supported FreeIPA Versions -------------------------- FreeIPA versions 4.4.0 and up are supported by the ipacert module. Requirements ------------ **Controller** * Ansible version: 2.14+ * Some tool to generate a certificate signing request (CSR) might be needed, like `openssl`. **Node** * Supported FreeIPA version (see above) Usage ===== Example inventory file ```ini [ipaserver] ipaserver.test.local ``` Example playbook to request a new certificate for a service: ```yaml --- - name: Certificate request hosts: ipaserver tasks: - name: Request a certificate for a web server ipacert: ipaadmin_password: SomeADMINpassword state: requested csr: | -----BEGIN CERTIFICATE REQUEST----- MIGYMEwCAQAwGTEXMBUGA1UEAwwOZnJlZWlwYSBydWxlcyEwKjAFBgMrZXADIQBs HlqIr4b/XNK+K8QLJKIzfvuNK0buBhLz3LAzY7QDEqAAMAUGAytlcANBAF4oSCbA 5aIPukCidnZJdr491G4LBE+URecYXsPknwYb+V+ONnf5ycZHyaFv+jkUBFGFeDgU SYaXm/gF8cDYjQI= -----END CERTIFICATE REQUEST----- principal: HTTP/www.example.com register: cert ``` Example playbook to revoke an existing certificate: ```yaml --- - name: Revoke certificate hosts: ipaserver tasks: - name Revoke a certificate ipacert: ipaadmin_password: SomeADMINpassword serial_number: 123456789 reason: 5 state: revoked ``` When revoking a certificate a mnemonic can also be used to set the revocation reason: ```yaml --- - name: Revoke certificate hosts: ipaserver tasks: - name Revoke a certificate ipacert: ipaadmin_password: SomeADMINpassword serial_number: 123456789 reason: cessationOfOperation state: revoked ``` Example to hold a certificate (alias for revoking a certificate with reason `certificateHold (6)`): ```yaml --- - name: Hold a certificate hosts: ipaserver tasks: - name: Hold certificate ipacert: ipaadmin_password: SomeADMINpassword serial_number: 0xAB1234 state: held ``` Example playbook to release hold of certificate (may be used with any revoked certificates, despite of the rovoke reason): ```yaml --- - name: Release hold hosts: ipaserver tasks: - name: Take a revoked certificate off hold ipacert: ipaadmin_password: SomeADMINpassword serial_number: 0xAB1234 state: released ``` Example playbook to retrieve a certificate and save it to a file in the target node: ```yaml --- - name: Retriev certificate hosts: ipaserver tasks: - name: Retrieve a certificate and save it to file 'cert.pem' ipacert: ipaadmin_password: SomeADMINpassword certificate_out: cert.pem state: retrieved ``` ipacert ------- Variable | Description | Required -------- | ----------- | -------- `ipaadmin_principal` | The admin principal is a string and defaults to `admin` | no `ipaadmin_password` | The admin password is a string and is required if there is no admin ticket available on the node | no `ipaapi_context` | The context in which the module will execute. Executing in a server context is preferred. If not provided context will be determined by the execution environment. Valid values are `server` and `client`. | no `ipaapi_ldap_cache` | Use LDAP cache for IPA connection. The bool setting defaults to yes. (bool) | no `csr` | X509 certificate signing request, in PEM format. | yes, if `state: requested` `principal` | Host/service/user principal for the certificate. | yes, if `state: requested` `add` \| `add_principal` | Automatically add the principal if it doesn't exist (service principals only). (bool) | no `profile_id` \| `profile` | Certificate Profile to use | no `ca` | Name of the issuing certificate authority. | no `chain` | Include certificate chain in output. (bool) | no `serial_number` | Certificate serial number. (int) | yes, if `state` is `retrieved`, `held`, `released` or `revoked`. `revocation_reason` \| `reason` | Reason for revoking the certificate. Use one of the reason strings, or the corresponding value: "unspecified" (0), "keyCompromise" (1), "cACompromise" (2), "affiliationChanged" (3), "superseded" (4), "cessationOfOperation" (5), "certificateHold" (6), "removeFromCRL" (8), "privilegeWithdrawn" (9), "aACompromise" (10) | yes, if `state: revoked` `certificate_out` | Write certificate (chain if `chain` is set) to this file, on the target node. | no `state` | The state to ensure. It can be one of `requested`, `held`, `released`, `revoked`, or `retrieved`. `held` is the same as revoke with reason "certificateHold" (6). `released` is the same as `cert-revoke-hold` on IPA CLI, releasing the hold status of a certificate. | yes Return Values ============= Values are returned only if `state` is `requested` or `retrieved` and if `certificate_out` is not defined. Variable | Description | Returned When -------- | ----------- | ------------- `certificate` | Certificate fields and data. (dict)
Options: | if `state` is `requested` or `retrieved` and if `certificate_out` is not defined   | `certificate` - Issued X509 certificate in PEM encoding. Will include certificate chain if `chain: true`. (list) | always   | `san_dnsname` - X509 Subject Alternative Name. | When DNSNames are present in the Subject Alternative Name extension of the issued certificate.   | `issuer` - X509 distinguished name of issuer. | always   | `subject` - X509 distinguished name of certificate subject. | always   | `serial_number` - Serial number of the issued certificate. (int) | always   | `revoked` - Revoked status of the certificate. (bool) | if certificate was revoked   | `owner_user` - The username that owns the certificate. | if `state: retrieved` and certificate is owned by a user   | `owner_host` - The host that owns the certificate. | if `state: retrieved` and certificate is owned by a host   | `owner_service` - The service that owns the certificate. | if `state: retrieved` and certificate is owned by a service   | `valid_not_before` - Time when issued certificate becomes valid, in GeneralizedTime format (YYYYMMDDHHMMSSZ) | always   | `valid_not_after` - Time when issued certificate ceases to be valid, in GeneralizedTime format (YYYYMMDDHHMMSSZ) | always Authors ======= Sam Morris Rafael Jeffman