Conjur Ansible Role

This Ansible role allows you to give a host a Conjur machine identity. With this identity, the host can securely retrieve secrets using the Summon tool.

Suggested Reading

• To learn more about Conjur, check it out here.
• For details on integrating Conjur with Ansible, see the Integration Documentation.
• To learn about Summon, which helps you deliver secret values to your applications, visit the Summon Webpage.
• For more integration options with Conjur, check the Conjur documentation.

Requirements

• Conjur v1+ or Conjur Enterprise (former DAP) v10+
• Conjur Enterprise v4
• Ansible v2.8

If you are using Ansible v2.9+, consider using our Ansible Collection.

Using ansible-conjur-host-identity with Conjur Open Source

If you're using this project with Conjur Open Source, we strongly recommend selecting the version of this project based on the latest Conjur OSS suite release. The maintainers conduct extra tests on these releases for better compatibility. Whenever possible, update your Conjur version to align with the latest release; for integrations, choose the release that matches your Conjur version. If you have questions, reach out to us on Discourse.

Usage Instructions

To install the Conjur role, run the following command in your playbook directory:

$ ansible-galaxy install cyberark.conjur-host-identity

The Conjur role helps you to "Conjurize" or create the Conjur identity of a remote node via Ansible. This node then receives minimal access rights to retrieve the secrets it needs securely.

Role Variables

• conjur_appliance_url *: The URL for the Conjur or Conjur Enterprise instance you are using. For a high-availability master cluster, use the master load balancer's URL.
• conjur_account *: The account name for the Conjur instance.
• conjur_host_factory_token *: A Host Factory token for layer enrollment. Set this in the environment on the Ansible host.
• conjur_host_name *: The name of the host identity for the host factory to create.
• conjur_ssl_certificate: The PEM-encoded x509 CA certificate chain for your Conjur Enterprise instance. Obtain this by running:

  $ openssl s_client -showcerts -servername [CONJUR_DNS_NAME] -connect [CONJUR_DNS_NAME]:443 < /dev/null 2> /dev/null
  

• conjur_validate_certs: A boolean to specify if the client should validate the Conjur server certificates.
• summon.version: Version of Summon to install, default is 0.8.3.
• summon_conjur.version: Version of the Summon-Conjur provider to install, default is 0.5.3.

The variables marked with * are required. The other variables are necessary for HTTPS connections but not for HTTP.

Example Playbook

Here’s an example to configure a remote node with a Conjur identity and Summon:

- hosts: servers
  roles:
    - role: cyberark.conjur-host-identity
      conjur_appliance_url: 'https://conjur.myorg.com/api',
      conjur_account: 'myorg',
      conjur_host_factory_token: "{{lookup('env', 'HFTOKEN')}}",
      conjur_host_name: "{{inventory_hostname}}"

This example:

• Registers the host with Conjur, placing it in the specific layer identified by the host factory token.
• Installs Summon with the Summon-Conjur provider for secure secret retrieval from Conjur.

Summon & Service Managers

Once Summon is installed, connecting Conjur with a Service Manager (like SystemD) becomes easy. Here’s a simple SystemD file example connecting to Conjur:

[Unit]
Description=DemoApp
After=network-online.target

[Service]
User=DemoUser
ExecStart=/usr/local/bin/summon --yaml 'DB_PASSWORD: !var staging/demoapp/database/password' /usr/local/bin/myapp

This example uses Summon to fetch the password stored at staging/myapp/database/password, sets it as an environment variable DB_PASSWORD, and uses it in the demo application. With Summon, the secret is not stored on disk. If the service restarts, Summon will retrieve the password again when the application starts.

Dependencies

None

Recommendations

• Important: Include no_log: true for any play using sensitive data, to prevent logging that data.
• Set the minimum permissions for Ansible files. Ansible works using the permissions of the user running it.

Contributing

We welcome all kinds of contributions to this repository. For guidance on how to get started and details about our development processes, please refer to our contributing guide.

License

Copyright (c) 2020 CyberArk Software Ltd. All rights reserved.

This repository is licensed under Apache License 2.0 - see LICENSE for more information.