This collection contains components to be used with CyberArk Conjur & Conjur Enterprise hosted in Ansible Galaxy.
- Certification Level
- Requirements
- Installation
- Conjur Ansible Role
- Conjur Ansible Lookup Plugin
- Contributing
- License
This repo is a Certified level project. It's been reviewed by CyberArk to verify that it will securely work with CyberArk Enterprise as documented. In addition, CyberArk offers Enterprise-level support for these features. For more detailed information on our certification levels, see our community guidelines.
- An instance of CyberArk Conjur Open Source v1.x+ or CyberArk Conjur Enterprise (formerly DAP) v10.x+ accessible from the target node
- Ansible >= 2.13
Are you using this project with Conjur Open Source? Then we strongly recommend choosing the version of this project to use from the latest Conjur OSS suite release. Conjur maintainers perform additional testing on the suite release versions to ensure compatibility. When possible, upgrade your Conjur version to match the latest suite release; when using integrations, choose the latest suite release that matches your Conjur version. For any questions, please contact us on Discourse.
From terminal, run the following command:
ansible-galaxy collection install cyberark.conjur
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).
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.
conjur_appliance_url
(Required): URL of the running Conjur serviceconjur_account
(Required): Conjur account nameconjur_host_factory_token
(Required): Host Factory token for layer enrollment. This should be specified in the environment on the Ansible controlling host.conjur_host_name
(Required): Name of the host to be created.conjur_ssl_certificate
: Public SSL certificate of the Conjur endpointconjur_validate_certs
: Boolean value to indicate if the Conjur endpoint should validate certificatesstate
: Specifies whether to install of uninstall the Role on the specified nodessummon.version
: version of Summon to install. Default is0.8.2
.summon_conjur.version
: version of Summon-Conjur provider to install. Default is0.5.3
.
The variables not marked (Required)
are required for running with an HTTPS Conjur endpoint.
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'
conjur_account: 'myorg'
conjur_host_factory_token: "{{ lookup('env', 'HFTOKEN') }}"
conjur_host_name: "{{ inventory_hostname }}"
conjur_ssl_certificate: "{{ lookup('file', '/path/to/conjur.pem') }}"
conjur_validate_certs: yes
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.
Executing the following playbook will clean up configuration and identity files written to the specified remote nodes, as well as uninstalling Summon and the Summon Conjur provider:
- hosts: servers
roles:
- role: cyberark.conjur.conjur_host_identity
state: absent
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 to4
. 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.
-
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.
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.
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 nameCONJUR_APPLIANCE_URL
: URL of the running Conjur serviceCONJUR_CERT_FILE
: Path to the Conjur certificate fileCONJUR_CERT_CONTENT
: Content of the Conjur certificate (PEM format).CONJUR_AUTHN_LOGIN
: A valid Conjur host usernameCONJUR_AUTHN_API_KEY
: The api key that corresponds to the Conjur host usernameCONJUR_AUTHN_TOKEN_FILE
: Path to a file containing a valid Conjur auth token
In addition to specifying a certificate file (CONJUR_CERT_FILE), you can now provide the certificate content directly via the CONJUR_CERT_CONTENT variable. This is useful when you prefer to include the certificate in the form of a string (PEM format) instead of referencing a file on disk.
The lookup plugin will first attempt to use the CONJUR_CERT_CONTENT variable. If it is invalid or missing, the plugin will fall back to using the certificate file specified in the CONJUR_CERT_FILE.
- CONJUR_CERT_CONTENT as PEM format
You can provide the certificate directly as a string in PEM format inside the CONJUR_CERT_CONTENT environment variable. Ensure that the content includes the full certificate block starting with -----BEGIN CERTIFICATE----- and ending with -----END CERTIFICATE-----.
export CONJUR_CERT_CONTENT="-----BEGIN CERTIFICATE-----
your certificate content
-----END CERTIFICATE-----"
Once set, the plugin will look for this variable and use the certificate content as needed.
- CONJUR_CERT_FILE as File
If CONJUR_CERT_CONTENT is not set or is invalid, the plugin will attempt to use the certificate file specified in the CONJUR_CERT_FILE environment variable.
To specify the certificate file, set the environment variable like this:
export CONJUR_CERT_FILE="<path>/certificate.pem"
- If both CONJUR_CERT_CONTENT and CONJUR_CERT_FILE are missing or invalid, the plugin will return an error. This allows you to quickly diagnose the issue and ensure that the required certificate is provided.
None.
---
- hosts: localhost
tasks:
- name: Lookup variable in Conjur
debug:
msg: "{{ lookup('cyberark.conjur.conjur_variable', '/path/to/secret') }}"
---
ansible_host: <host>
ansible_ssh_private_key_file: "{{ lookup('cyberark.conjur.conjur_variable', 'path/to/secret-id', as_file=True) }}"
Note: Using the as_file=True
condition, the private key is stored in a temporary file and its path is written
in ansible_ssh_private_key_file
.
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.
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
.