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 policy Role for Ansible

This role enables "Policy as Code" for Venafi Trust Protection Platform or Venafi as a Service using Red Hat Ansible. With it, certificate policy documented by specification files can be applied to Venafi to ensure compliance with enterprise standards.

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 policy 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. Create a policy specification file sample_policy_spec.json

5. Write a simple playbook called, for example, policy_sample.yml.

   - hosts: localhost
     roles:
       - role: venafi.machine_identity.policy
         policy_spec_path: "/tmp/etc/ssl/sample_policy_spec.json"

6. Run the playbook.

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

   Running this playbook will create:

   Platform	Result
   Trust Protection	a policy folder with the values specified on sample_policy_spec.json on the path specified by the zone setting
   Venafi as a Service	an Application and Certificate Issuing Template with the values specified on sample_policy_spec.json with names given by the zone setting. (e.g. "Business App\Enterprise CIT")

   The --ask-vault-pass parameter is needed if you encrypted the credentials.yml file.

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.