Ansible Integration

Integrating PAM’s 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.

PAM 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 PAM 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 PAM SSH Proxy.

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

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

PAM 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 PAM Server using SSH protocol with the private key to facilitate automation.

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

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

Ansible should reference accounts in the form xtam-user%record-id where xtam-user is an PAM service user with the public key SSH authentication enabled and record-id is the PAM 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 PAM 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. PAM manages the destination connection itself, so Ansible reusing client connections to PAM is not useful to access session completed previously on the PAM server. It makes every other command to fail to retrieve any data from the destination server because PAM 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 PAM Vault when needed using the Ansible PAM Lookup Plugin.

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

The plugin can retrieve any sensitive field from the PAM 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 PAM Lookup Plugin using the link below and then deploy it according to Ansible documentation in project-, user-, or global- scope.

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

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

 

  • ANS_XTAM_URL is the PAM server URL in the form of https://xtam.company.com. Note that the plugin in this case expects PAM 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 – PAM service account for Ansible to access the vault for PAM Basic Authentication scenario. Note that this account has to have Record Control: Unlock permissions or higher for the records of interest.
  • ANS_XTAM_PASSWORD – PAM 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 PAM connectivity for the Data Lookup Plugin is configured, PAM 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 PAM 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 PAM record)

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

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