Ansible Integration

Integrating XTAM’s PAM (Privileged Access Management) Vault with Ansible.

Ansible is a popular open-source agentless automation tool, or platform, used for IT tasks such as configuration management, application deployment, intra-service orchestration, and provisioning.

Ansible works by connecting to your nodes (such as computers or network devices) and pushing out small programs, called “Ansible modules” to them.

These programs are written to be resource models of the desired state of the system.

Ansible then executes these modules (over SSH by default), and removes them when finished.

 

To connect to the nodes Ansible needs to know the account credentials such as logins, passwords or keys.

Ansible Vault encrypts credentials right inside Ansible modules and decrypts them when they are needed.

XTAM Vault is a server that securely stores and manages (including periodic update) credentials shared between multiple stakeholders in the organization including Ansible to ensure that every Ansible task execution uses the current set of credentials to connect to destination nodes.

 

There are two ways in which Ansible can use credentials from the XTAM Vault: Connection Brokering and Data Lookup.

Connection Brokering Integration

In the Connection Brokering scenario Ansible connects to remote nodes using SSH protocol with the traffic passed through the XTAM SSH Proxy.

In this scenario Ansible does not retrieve credentials from XTAM Vault but instead, relies on the XTAM SSH Proxy to broker connections to the destination node using the host and credentials from the XTAM Vault.

Ansible authenticates in the XTAM Server using the same XTAM service account using a public key.

XTAM SSH Proxy substitutes the destination host and account credentials in the SSH traffic initiated by the Ansible tasks.

 

In this Connection Brokering scenario Ansible does not manage credentials to the destination nodes.

Instead, Ansible only knows how to connect to the XTAM Server using SSH protocol with the private key to facilitate automation.

 

Please review the article about setting up a user in the XTAM SSH Server with public key authentication.

After the private key connection to the XTAM Server is established, Ansible should reference all nodes under management using the XTAM SSH server host.

Ansible should reference accounts in the form xtam-user%record-id where xtam-user is an XTAM service user with the public key SSH authentication enabled and record-id is the XTAM record ID describing the remote node managed by Ansible.

 

Note that Ansible first uploads small pieces of code to the temporary folder on the destination computer. Sometimes the default place is in the current user home folder. The problem with that is that Ansible assumes that the home folder name matches the user name Ansible connects to the destinations server instead of deriving the home folder from the destination system environment (whoami would work better instead but default Ansible scripts do not use that). In reality there is no such user or such folder in the destination system because XTAM substitutes the actual user credentials in the Ansible traffic to the real privileged account.

 

There are multiple ways to solve this problem. One of those is to make Ansible to maintain temporary files in the /tmp folder on the destination server to detach it from the user name Ansible thinks it uses to connect. To do that use a system environment variable

 

export ANSIBLE_REMOTE_TMP=/tmp

 

…or alternatively define Ansible variable

 

remote_tmp = /tmp/ansible

 

Also note that default Ansible configuration makes ssh to cache connections for some time to avoid making multiple consecutive connections. XTAM manages the destination connection itself, so Ansible reusing client connections to XTAM is not useful to access session completed previously on the XTAM server. It makes every other command to fail to retrieve any data from the destination server because XTAM is the entity managing connections and Ansible cached connections would not work.

 

To solve this issue, disable cached connections by Ansible by using the following environments variable although this operation could be probably done in many other ways in ssh, template, playbook or project level.

 

export ANSIBLE_SSH_ARGS=”-o ControlMaster=no”

Data Lookup Integration

In a Data Lookup scenario Ansible retrieves sensitive information from XTAM Vault when needed using the Ansible XTAM Lookup Plugin.

The Ansible XTAM Lookup Plugin could be used in any place where Ansible can use lookups.

The plugin can retrieve any sensitive field from the XTAM records to use in Ansible variables, rules or playbooks instead of hard coding this data in Ansible variables.

To enable data lookup integration, first download the Ansible XTAM Lookup Plugin using the link below and then deploy it according to Ansible documentation in project-, user-, or global- scope.

 

Ansible XTAM Lookup Plugin: https://www.xtontech.com/wp-content/uploads/files/xtam.py

The Ansible XTAM Lookup Plugin uses the following environment variables to connect to the XTAM Server

 

  • ANS_XTAM_URL is the XTAM server URL in the form of https://xtam.company.com . Note that the plugin in this case expects XTAM to respond on the URL https://xtam.company.com/xtam and for Federated Sign-In on the URL https://xtam.company.com/cas . However, this parameter should only specify the URL without /xtam/ or /cas/ paths. In case of custom port use the URL in the form https://xtam.company.com:port
  • ANS_XTAM_LOGIN – XTAM service account for Ansible to access the vault for XTAM Basic Authentication scenario. Note that this account has to have Record Control: Unlock permissions or higher for the records of interest.
  • ANS_XTAM_PASSWORD – XTAM service account password
  • ANS_XTAM_TOKEN as an alternative to using ANS_XTAM_LOGIN and ANS_XTAM_PASSWORD for a Federated Sign-In scenario. Use the following link describing Authentication Tokens configuration and their use.

Note that for newer Mac OS computers, per Ansible guidelines, you have also have to set the following environment variable:

 

OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES

 

After Ansible XTAM connectivity for the Data Lookup Plugin is configured, XTAM lookups could be used in any place Ansible allows lookups using the following syntax

Copy
lookup('xtam', 'RECORD-ID FIELD-NAME')

 

Where

  • RECORD-ID is the XTAM record ID describing the remote node asset
  • FIELD-NAME is the field name to return by this lookup (such as User, Password or any other out of the box or custom fields in the XTAM record)

For example, below is the group variables definition for certain group scan retrieving the user and password data from XTAM Vault record i-4bbAmkj4QYq :

Copy
ansible_user: "{{lookup('xtam', 'i-4bbAmkj4QYq User')}}"
ansible_password: "{{lookup('xtam', 'i-4bbAmkj4QYq Password')}}"