/ home / freeipa / freeipa.ansible_freeipa / 1.11.1 / module / ipacert

freeipa.ansible_freeipa.ipacert (1.11.1) — module

Manage FreeIPA certificates

Authors: Sam Morris (@yrro), Rafael Guterres Jeffman (@rjeffman)

preview | supported by community

Install collection

Install with ansible-galaxy collection install freeipa.ansible_freeipa:==1.11.1

Add to requirements.yml

  collections:
    - name: freeipa.ansible_freeipa
      version: 1.11.1

Description

Manage FreeIPA certificates

Usage examples

Scanned by Steampunk Spotter

- name: Request a certificate for a web server
  freeipa.ansible_freeipa.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

Scanned by Steampunk Spotter

- name: Request certificate for a user, with an appropriate profile.
  freeipa.ansible_freeipa.ipacert:
    ipaadmin_password: SomeADMINpassword
    csr: |
      -----BEGIN CERTIFICATE REQUEST-----
      MIIBejCB5AIBADAQMQ4wDAYDVQQDDAVwaW5reTCBnzANBgkqhkiG9w0BAQEFAAOB
      jQAwgYkCgYEA7uChccy1Is1FTM0SF23WPYW472E3ozeLh2kzhKR9Ni6FLmeEGgu7
      /hicR1VwvXHYkNwI1tpW9LqxRVvgr6vheqHySljrBcoRfshfYvKejp03l2327Bfq
      BNxXqLcHylNEyg8SH0u63bWyxtgoDBfdZwdGAhYuJ+g4ev79J5eYoB0CAwEAAaAr
      MCkGCSqGSIb3DQEJDjEcMBowGAYHKoZIzlYIAQQNDAtoZWxsbyB3b3JsZDANBgkq
      hkiG9w0BAQsFAAOBgQADCi5BHDv1mrBFDWqYytFpQ1mrvr/mdax3AYXxNL2UEV8j
      AqZAFTEnJXL/u1eVQtI1yotqxakyUBN4XZBP2CBgJRO93Mtry8cgvU1sPdU8Mavx
      5gSnlP74Hio2ziscWWydlxpYxFx0gkKvu+0nyIpz954SVYwQ2wwk5FRqZnxI5w==
      -----END CERTIFICATE REQUEST-----
    principal: pinky
    profile_id: IECUserRoles
    state: requested

Scanned by Steampunk Spotter

- name: Temporarily hold a certificate
  freeipa.ansible_freeipa.ipacert:
    ipaadmin_password: SomeADMINpassword
    serial_number: 12345
    state: held

Scanned by Steampunk Spotter

- name: Remove a certificate hold
  freeipa.ansible_freeipa.ipacert:
    ipaadmin_password: SomeADMINpassword
    state: released
    serial_number: 12345

Scanned by Steampunk Spotter

- name: Permanently revoke a certificate issued by a lightweight sub-CA
  freeipa.ansible_freeipa.ipacert:
    ipaadmin_password: SomeADMINpassword
    state: revoked
    ca: vpn-ca
    serial_number: 0x98765
    reason: keyCompromise

Scanned by Steampunk Spotter

- name: Retrieve a certificate
  freeipa.ansible_freeipa.ipacert:
    ipaadmin_password: SomeADMINpassword
    serial_number: 12345
    state: retrieved
  register: cert_retrieved

Inputs

    
ca:
    description: Name of the issuing certificate authority.
    required: false
    type: str

add:
    aliases:
    - add_principal
    description: 'Automatically add the principal if it doesn''t exist (service

      principals only). Only available if `state: requested`.

      '
    required: false
    type: bool

csr:
    description: 'X509 certificate signing request, in RFC 7468 PEM encoding.

      Only available if `state: requested`, required if `csr_file` is not

      provided.

      '
    type: str

state:
    choices:
    - requested
    - held
    - released
    - revoked
    - retrieved
    description: 'The state to ensure. `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.

      '
    required: true
    type: str

profile:
    aliases:
    - profile_id
    description: Certificate Profile to use.
    required: false
    type: str

csr_file:
    description: 'Path to file with X509 certificate signing request, in RFC 7468 PEM

      encoding. Only available if `state: requested`, required if `csr_file`

      is not provided.

      '
    type: str

principal:
    description: 'Host/service/user principal for the certificate.

      Required if `state: requested`. Only available if `state: requested`.

      '
    type: str

serial_number:
    description: 'Certificate serial number. Cannot be used with `state: requested`.

      Required for all states, except `requested`.

      '
    type: int

ipaapi_context:
    choices:
    - server
    - client
    description: '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.

      '
    required: false
    type: str

certificate_out:
    description: 'Write certificate (chain if `chain` is set) to this file, on the target

      node.. Use only when `state` is `requested` or `retrieved`.

      '
    required: false
    type: str

ipaadmin_password:
    description: The admin password.
    required: false
    type: str

ipaapi_ldap_cache:
    default: true
    description: Use LDAP cache for IPA connection.
    type: bool

revocation_reason:
    aliases:
    - reason
    description: '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).

      Use only if `state: revoked`. Required if `state: revoked`.

      '
    type: raw

ipaadmin_principal:
    default: admin
    description: The admin principal.
    type: str

Outputs

certificate:
  contains:
    certificate:
      description: 'Issued X509 certificate in PEM encoding. Will include certificate

        chain if `chain: true` is used.

        '
      elements: str
      returned: always
      type: list
    issuer:
      description: X509 distinguished name of issuer.
      returned: always
      sample: CN=Certificate Authority,O=EXAMPLE.COM
      type: str
    owner_host:
      description: The host that owns the certificate.
      returned: when `state` is `retrieved`
      type: str
    owner_service:
      description: The service that owns the certificate.
      returned: when `state` is `retrieved`
      type: str
    owner_user:
      description: The username that owns the certificate.
      returned: when `state` is `retrieved`
      type: str
    revoked:
      description: Revoked status of the certificate.
      returned: always
      type: bool
    san_dnsname:
      description: X509 Subject Alternative Name.
      elements: str
      returned: 'when DNSNames are present in the Subject Alternative Name

        extension of the issued certificate.

        '
      sample:
      - www.example.com
      - other.example.com
      type: list
    serial_number:
      description: Serial number of the issued certificate.
      returned: always
      sample: 902156300
      type: int
    subject:
      description: X509 distinguished name of certificate subject.
      returned: always
      sample: CN=www.example.com,O=EXAMPLE.COM
      type: str
    valid_not_after:
      description: 'Time when issued certificate ceases to be valid,

        in GeneralizedTime format (YYYYMMDDHHMMSSZ).

        '
      returned: always
      type: str
    valid_not_before:
      description: 'Time when issued certificate becomes valid, in

        GeneralizedTime format (YYYYMMDDHHMMSSZ).

        '
      returned: always
      type: str
  description: Certificate fields and data.
  returned: 'if `state` is `requested` or `retrived` and `certificate_out`

    is not defined.

    '
  type: dict