diff options
Diffstat (limited to 'collections-debian-merged/ansible_collections/cyberark/conjur/README.md')
| -rw-r--r-- | collections-debian-merged/ansible_collections/cyberark/conjur/README.md | 208 |
1 files changed, 208 insertions, 0 deletions
diff --git a/collections-debian-merged/ansible_collections/cyberark/conjur/README.md b/collections-debian-merged/ansible_collections/cyberark/conjur/README.md new file mode 100644 index 00000000..ae9219bd --- /dev/null +++ b/collections-debian-merged/ansible_collections/cyberark/conjur/README.md @@ -0,0 +1,208 @@ + + +# CyberArk Ansible Conjur Collection + +This collection contains components to be used with CyberArk Conjur & DAP (Dynamic Access Provider) +hosted in [Ansible Galaxy](https://galaxy.ansible.com/cyberark/conjur). + +## Table of Contents + +* [Requirements](#requirements) +* [Installation](#installation) +* [Conjur Ansible Role](#conjur-ansible-role) + + [Usage](#usage) + + [Role Variables](#role-variables) + + [Example Playbook](#example-playbook) + + [Summon & Service Managers](#summon---service-managers) + + [Recommendations](#recommendations) +* [Conjur Ansible Lookup Plugin](#conjur-ansible-lookup-plugin) + + [Environment variables](#environment-variables) + + [Role Variables](#role-variables-1) + + [Examples](#examples) + - [Retrieve a secret in a Playbook](#retrieve-a-secret-in-a-playbook) + - [Retrieve a private key in an Inventory file](#retrieve-a-private-key-in-an-inventory-file) +* [Contributing](#contributing) +* [License](#license) + +<!-- Table of contents generated with markdown-toc +http://ecotrust-canada.github.io/markdown-toc/ --> + +## Requirements + +- An instance of [CyberArk Conjur Open Source](https://www.conjur.org) v1.x+ or [CyberArk Dynamic + Access + Provider](https://docs.cyberark.com/Product-Doc/OnlineHelp/AAM-DAP/Latest/en/Content/Resources/_TopNav/cc_Home.htm) + v10.x+ accessible from the target node +- Ansible >= 2.9 + +## Using ansible-conjur-collection with Conjur OSS + +Are you using this project with [Conjur OSS](https://github.com/cyberark/conjur)? Then we +**strongly** recommend choosing the version of this project to use from the latest [Conjur OSS +suite release](https://docs.conjur.org/Latest/en/Content/Overview/Conjur-OSS-Suite-Overview.html). +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](https://docs.conjur.org/Latest/en/Content/ReleaseNotes/ConjurOSS-suite-RN.htm); +when using integrations, choose the latest suite release that matches your Conjur version. For any +questions, please contact us on [Discourse](https://discuss.cyberarkcommons.org/c/conjur/5). + +## Installation + +From terminal, run the following command: +```sh +ansible-galaxy collection install cyberark.conjur +``` + +## Conjur Ansible Role + +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](#conjur-ansible-lookup-plugin) or using the [Summon](https://github.com/cyberark/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](https://developer.conjur.net/reference/services/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: +```yml +- 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. + +### 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: + +```ini +[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](#conjur-ansible-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. + +### Examples + +#### Retrieve a secret in a Playbook + +```yaml +--- +- hosts: localhost + tasks: + - name: Lookup variable in Conjur + debug: + msg: "{{ lookup('cyberark.conjur.conjur_variable', '/path/to/secret') }}" +``` + +#### Retrieve a private key in an Inventory file + +```yaml +--- +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`. + +## 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][contrib]. + +[contrib]: https://github.com/cyberark/ansible-conjur-collection/blob/master/CONTRIBUTING.md + +## 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`](LICENSE). |