CyberArk Ansible Conjur Collection

This collection contains components to be used with CyberArk Conjur & DAP (Dynamic Access Provider) hosted in Ansible Galaxy.

Table of Contents

• Requirements
• Installation
• Conjur Ansible Role
  • Usage
  • Role Variables
  • Example Playbook
  • Summon & Service Managers
  • Recommendations
• Conjur Ansible Lookup Plugin
  • Environment variables
  • Role Variables
  • Example Playbook
• Contributing
• License

Requirements

• An instance of CyberArk Conjur Open Source v1.x+ or CyberArk Dynamic Access Provider v10.x+ accessible from the target node
• Ansible >= 2.9

Installation

From terminal, run the following command:

ansible-galaxy collection install cyberark.conjur

Conjur Ansible Role

NOTE: This role is currently not available in releases installed through Ansible Galaxy, but will be added in the next release. Follow issue #30 for updates.

This Ansible role provides the ability to grant Conjur machine identity to a host. Based on that identity, secrets can then be retrieved securely using the Conjur Lookup Plugin or using the Summon tool (installed on hosts with identities created by this role).

Usage

The Conjur role provides a method to establish the Conjur identity of a remote node with Ansible. The node can then be granted least-privilege access to retrieve the secrets it needs in a secure manner.

Role Variables

• conjur_appliance_url (Optional): URL of the running Conjur service
• conjur_account (Optional): Conjur account name
• conjur_host_factory_token (Optional): Host Factory token for layer enrollment. This should be specified in the environment on the Ansible controlling host.
• conjur_host_name (Optional): Name of the host to be created.
• conjur_ssl_certificate: Public SSL certificate of the Conjur endpoint
• conjur_validate_certs: Boolean value to indicate if the Conjur endpoint should validate certificates
• summon.version: version of Summon to install. Default is 0.8.2.
• summon_conjur.version: version of Summon-Conjur provider to install. Default is 0.5.3.

The variables marked with (Optional) are not required fields. All other variables are required for running with an HTTPS Conjur endpoint.

Example Playbook

Configure a remote node with a Conjur identity and Summon:

- hosts: servers
  roles:
    - role: cyberark.conjur.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 {{ inventory_hostname }} with Conjur, adding it into the Conjur policy layer defined for the provided host factory token.
• Installs Summon with the Summon Conjur provider for secret retrieval from Conjur.

Summon & Service Managers

With Summon installed, using Conjur with a Service Manager (like systemd) becomes a snap. Here's a simple example of a systemd file connecting to Conjur:

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

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

Note: When connecting to Conjur 4 (Conjur Enterprise), Summon requires the environment variable CONJUR_MAJOR_VERSION set to 4. You can provide it by uncommenting the relevant line above.

The above example uses Summon to retrieve the password stored in staging/myapp/database/password, set it to an environment variable DB_PASSWORD, and provide it to the demo application process. Using Summon, the secret is kept off disk. If the service is restarted, Summon retrieves the password as the application is started.

Recommendations

• Add no_log: true to each play that uses sensitive data, otherwise that data can be printed to the logs.

• Set the Ansible files to minimum permissions. Ansible uses the permissions of the user that runs it.

Conjur Ansible Lookup Plugin

Fetch credentials from CyberArk Conjur using the controlling host's Conjur identity or environment variables.

The controlling host running Ansible must have a Conjur identity, provided for example by the ConjurAnsible role.

Environment variables

The following environment variables will be used by the lookup plugin to authenticate with the Conjur host, if they are present on the system running the lookup plugin.

• CONJUR_ACCOUNT : The Conjur account name
• CONJUR_APPLIANCE_URL : URL of the running Conjur service
• CONJUR_CERT_FILE : Path to the Conjur certificate file
• CONJUR_AUTHN_LOGIN : A valid Conjur host username
• CONJUR_AUTHN_API_KEY : The api key that corresponds to the Conjur host username
• CONJUR_AUTHN_TOKEN_FILE : Path to a file containing a valid Conjur auth token

Role Variables

None.

Example Playbook

---
- hosts: localhost
  tasks:
  - name: Lookup variable in Conjur
    debug:
      msg: "{{ lookup('cyberark.conjur.conjur_variable', '/path/to/secret') }}"

Contributing

We welcome contributions of all kinds to this repository. For instructions on how to get started and descriptions of our development workflows, please see our contributing guide.

License

Copyright (c) 2020 CyberArk Software Ltd. All rights reserved. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

For the full license text see LICENSE.