README.md

This open source project is community-supported. To report a problem or share an idea, use Issues; and if you have a suggestion for fixing the issue, please include those details, too. In addition, use Pull Requests to contribute actual bug fixes or proposed enhancements. We welcome and appreciate all contributions. Got questions or want to discuss something with our team? Join us on Slack!

Venafi certificate Role for Ansible

This role adds certificate enrollment capabilities to Red Hat Ansible by seamlessly integrating with the Venafi Trust Protection Platform or Venafi as a Service in a manner that ensures compliance with corporate security policy and provides visibility into certificate issuance enterprise wide.

🚗 Test drive our integration examples today

Let us show you step-by-step how to add certificates to your Infrastucture as Code automation with Ansible.

Products	Available integration examples...
	How to configure secure application delivery using F5 BIG-IP and the Venafi Role Ansible
	How to configure secure application delivery using Citrix ADC and the Venafi Role for Ansible
	How to secure and configure Microsoft IIS using the Venafi Role for Ansible

NOTE If you don't see an example for a product you use, check back later. We're working hard to add more integration examples.

Requirements

Review the Venafi prerequisites, then install Ansible and VCert-Python (v0.11.2 or higher) using pip:

pip install ansible vcert --upgrade

Using with Ansible Galaxy

For more information about Ansible Galaxy, go to https://galaxy.ansible.com/docs/using/installing.html

1. Install the Machine Identity Collection from Ansible Galaxy:

   ansible-galaxy collection install venafi.machine_identity

2. Create the credentials.yml and populate it with connection parameters:

   Trust Protection Platform:

   cat <<EOF >>credentials.yml
   access_token: 'p0WTt3sDPbzm2BDIkoJROQ=='
   url: 'https://tpp.venafi.example'
   zone: "DevOps\\Ansible"
   trust_bundle: "/path/to/bundle.pem"
   EOF

   Venafi as a Service:

   cat <<EOF >>credentials.yml
   token: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
   zone: 'Business App\\Enterprise CIT'
   EOF

   Venafi as a Service EU:

   cat <<EOF >>credentials.yml
   url: 'https://api.venafi.eu'
   token: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
   zone: 'Business App\\Enterprise CIT'
   EOF

   The certificate role supports the following connection and credential settings:

   Variable Name	Description
   access_token	Trust Protection Platform access token for the "ansible-by-venafi" API Application
   password	[DEPRECATED] Trust Protection Platform WebSDK password, use access_token if possible
   test_mode	When "true", the role operates without connecting to Trust Protection Platform or Venafi as a Service
   token	Venafi as a Service API key
   trust_bundle	Text file containing trust anchor certificates in PEM (text) format, generally required for Trust Protection Platform
   url	Venafi service URL (e.g. "https://tpp.venafi.example")
   user	[DEPRECATED] Trust Protection Platform WebSDK username, use access_token if possible
   zone	Policy folder for TPP or Application name and Issuing Template API Alias for VaaS (e.g. "Business App\Enterprise CIT")

3. Use ansible-vault to encrypt the credentials.yml file using a password. This is optional but highly recommended. As long as you know the password you can always decrypt the file to make changes and then re-encrypt it. Go to https://docs.ansible.com/ansible/latest/user_guide/vault.html for more information.

   ansible-vault encrypt credentials.yml

4. Write a simple playbook called, for example, sample.yml.

   - hosts: localhost
     roles:
       - role: venafi.machine_identity.certificate
         certificate_common_name: "certificate.example.com" 
         certificate_cert_dir: "/tmp/etc/ssl"

5. Run the playbook.

   ansible-playbook sample.yml --ask-vault-pass

   Running the playbook will generate a certificate and place it into folder in /tmp/etc/ssl/ directory. The --ask-vault-pass parameter is needed if you encrypted the credentials.yml file.

6. Additional playbook variables can be added to specify properties of the certificate and key pair, file locations, and to override default behaviors.

   cat variables.yml

   The following is the list of variables accepted by the certificate role:

   Variable Name	Description
   credentials_file	Name of the file containing Venafi credentials and connection settings Default: credentials.yml
   certificate_alt_name	Comma separated list of Subject Alternative Names to request for the certificate. Prefix each value with the SAN type. Example: "DNS:host.example.com,IP:10.20.30.40,email:me@example.com"
   certificate_before_expired_hours	Number of hours prior to the expiration of the certificate before it can be renewed Default: 72
   certificate_cert_dir	Local parent directory where the cryptographic assets will be stored Default: "/etc/ssl/{{ certificate_common_name }}"
   certificate_cert_path	Local directory where certificate files will be stored Default: {{ certificate_cert_dir }}/{{ certificate_common_name }}.pem"
   certificate_chain_option	Specifies whether the root CA certificate appears "last" (default) or "first" in the chain file
   certificate_chain_path	Local directory where certificate chain files will be stored Default: "{{ certificate_cert_dir }}/{{ certificate_common_name }}.chain.pem"
   certificate_common_name	Common Name to request for the certificate. Default: "{{ ansible_fqdn }}"
   certificate_copy_private_key_to_remote	Specifies whether to copy the private key file to the remote host Default: true
   certificate_csr_origin	Specifies the source of the CSR used to request a certificate. Default: "local" Options: "local" - Generates CSR locally, "provided" - CSR is provided, or "service" - Venafi generates CSR
   certificate_csr_path	Local directory where certificate signing request files will be stored Default: "{{ certificate_cert_dir }}/{{ certificate_common_name }}.csr"
   certificate_custom_fields	Map of custom-defined attributes for the certificate, declared as key-value format. Example: certificate_custom_fields: custom: asd cfList: item3 cfListMulti: [tier1, tier4]
   certificate_force	Specifies whether to request a new certificate every time the playbook is run Default: false
   certificate_issuer_hint	Issuer of the certificate. Ignored when platform is not TPP. Use in combination with validity_hours to specify the validity period of a certificate on TPP. Default: "DEFAULT" Options: "DEFAULT", "DIGICERT", "ENTRUST", or "MICROSOFT"
   certificate_pkcs12_format	Use PKCS12 format to serialize the certificate. Default: false
   certificate_privatekey_curve	Elliptic Curve for ECDSA keys Default: "P256" (from VCert)
   certificate_privatekey_passphrase	Password to use for encrypting the private key
   certificate_privatekey_path	Local directory where private key files will be stored Default: "{{ certificate_cert_dir }}/{{ certificate_common_name }}.key"
   certificate_privatekey_size	Key size in bits for RSA keys Default: "2048" (from VCert) Options: "1024", "2048" or "4096"
   certificate_privatekey_type	Key algorithm Default: "RSA" (from VCert) Options: "RSA" or "ECDSA"
   certificate_remote_cert_path	Directory on remote host where certificate files will be stored Default: "{{ certificate_cert_dir }}/{{ certificate_common_name }}.pem"
   certificate_remote_chain_path	Directory on remote host where certificate chain files will be stored Default: "{{ certificate_cert_dir }}/{{ certificate_common_name }}.chain.pem"
   certificate_remote_execution	Specifies whether cryptographic assets will be generated remotely, or locally and then provisioned to the remote host Default: false
   certificate_remote_privatekey_path	Directory on remote host where private key files will be stored Default: "{{ certificate_cert_dir }}/{{ certificate_common_name }}.key"
   certificate_renew	Specifies whether to renew the certificate if it is within the "before_expired_hours" window when the playbook is run Default: true
   certificate_validity_hours	Indicates the validity period of the certificate before it expires

   Defaults are defined in the defaults/main.yml file.

Preparing a Docker demo environment for running Ansible

1. For this demo, move to the root folder of this collection.

2. Prepare the demo environment. If you want to use your own inventory, update the tests/certificate/inventory file.

   1. To run our test/demo playbook you'll need the Docker provisioning role. Download it into the /tests/certificate/roles/provision_docker directory:

      git clone https://github.com/chrismeyersfsu/provision_docker.git tests/certificate/roles/provision_docker

   2. Then build the Docker images needed for the demo playbook:

      docker build ./tests/certificate --tag certificate-local-ansible-test

   Demo certificates will be placed in the /tmp/ansible/etc/ssl directory on the Ansible host. From there they will be distributed to the /etc/ssl/ directory of remote hosts.

3. Generate a credentials file for either Trust Protection Platform or Venafi as a Service as described in the above section.

4. Run the Ansible playbook (remove docker_demo=true if you want to use your own inventory). The contents of credentials.yml will be used to decide whether Trust Protection Platform or Venafi as a Service is used. If you set the token parameter, the playbook assumes you are using Venafi as a Service. If you set the access_token or password parameters, the playbook assumes you are using Trust Protection Platform.

   cd ./tests/certificate
   ansible-playbook -i inventory \
     venafi-playbook-example.yml \
     --extra-vars "credentials_file=credentials.yml docker_demo=true" \
     --ask-vault-pass

   You will be prompted for the password for decrypting the credentials.yml as before. The source file for the credentials can be overridden using the credentials_file variable and this can be specified on the command line using the --extra-vars parameter as shown.

Sample Playbook

- hosts: servers
  roles:
    - role: "venafi.machine_identity.certificate"
      certificate_common_name: "{{ ansible_fqdn }}.venafi.example.com"
      certificate_cert_dir: "/tmp/ansible/etc/ssl/{{ certificate_common_name }}"
      certificate_cert_path: "{{ certificate_cert_dir }}/{{ certificate_common_name }}.pem"
      certificate_chain_path: "{{ certificate_cert_dir }}/{{ certificate_common_name }}.chain.pem"
      certificate_privatekey_path: "{{ certificate_cert_dir }}/{{ certificate_common_name }}.key"
      certificate_csr_path: "{{ certificate_cert_dir }}/{{ certificate_common_name }}.csr"

      # Where to execute venafi_certificate module. If set to false, certificate will be
      # created on ansible master host and then copied to the remote server.
      certificate_remote_execution: false
      # Remote location where to place the certificate.
      certificate_remote_cert_dir: "/etc/ssl"
      certificate_remote_cert_path: "{{ certificate_remote_cert_dir }}/{{ certificate_common_name }}.pem"
      certificate_remote_chain_path: "{{ certificate_remote_cert_dir }}/{{ certificate_common_name }}.chain.pem"
      certificate_remote_privatekey_path: "{{ certificate_remote_cert_dir }}/{{ certificate_common_name }}.key"
      # Set to false if you don't want to copy private key to remote location.
      certificate_copy_private_key_to_remote: true

For playbook examples look into venafi-playbook-example.yml file. For role examples look into venafi-role-playbook-example.yml file

For more information about using roles go to https://docs.ansible.com/ansible/latest/user_guide/playbooks_reuse_roles.html

License

Copyright © Venafi, Inc. All rights reserved.

This solution is licensed under the Apache License, Version 2.0. See LICENSE for the full license text.

Please direct questions/comments to opensource@venafi.com.