Ansible Lookup Plugin

With Lookup Plugin, you can manage Axidian Privilege credentials directly in Ansible playbooks.
All requests to retrieve and view credentials are logged in the Events journal.

Note

Application to Application Password Management (AAPM) method is used to manage Axidian Privilege account credentials.

Requirements

The following is required to work with Ansible Lookup Plugin:

• Python 3.9 or higher
• Ansible 2.14 or higher
• AAPM license

Prerequisites

To set up Ansible Lookup Plugin:

1. Navigate to the folder containing the AAPM package for Python SDK and run the command:
   
   

   pip install pam_aapm-3.4.0-py3-none-any.whl
2. Navigate to the folder containing the Lookup Plugin distribution for Ansible Collection and run the command:
   
   

   ansible-galaxy collection install pam_aapm-3.4.0.tar.gz
3. Open the Axidian Privilege administrator console and add an application.
4. For the application, add a permission with the Allow view account credentials option enabled.
   The permission allows the application to use passwords and SSH keys of PAM accounts.
5. Assign application administrators who can view the application password.
6. Open the Axidian Privilege user console and go to the Applications tab.
7. View the application password and save it.

Next, configure Ansible to gain access to the Axidian Privilege server.

Ansible Configuration

To establish a connection to the Axidian Privilege server and obtain access tokens, configure Ansible using one of the following methods:

• Configuration file ansible.cfg — specify the variables in the file if the configuration does not change between scenario runs. It is recommended to encrypt credentials or pass them through environment variables.
• Environment variables — specify the variables in the terminal before running the scenario. Variables exist only within the current session. Recommended for use in CI/CD automations.
• Ansible playbook — pass parameters as named arguments when calling the lookup() function. This method is suitable when you need to connect to a different server or override a parameter, such as ca_cert.

For more details on how the scenario works when the configuration is defined in multiple places, see the Ansible documentation.

Configuration parameters

Parameter	Environment variable	Requirement	Description
idp_server	PAM_IDP_SERVER	Required	URL of the Axidian Privilege IdP component
core_server	PAM_CORE_SERVER	Required	URL of the Axidian Privilege Core component
username	PAM_USERNAME	Required	Application name
password	PAM_PASSWORD	Required	Password of the specified application. The application administrator can view the password in the user console.
timeout	PAM_TIMEOUT	Optional	Request response timeout, sec. Default value: 30.0.
verify_ssl	PAM_VERIFY_SSL	Optional	Server SSL certificate verification: True — required False — not required Default value: True. Note: Enabled verification reduces the risk of data interception. If you have disabled verification, it is recommended to note this in the script and leave a comment.
ca_cert	PAM_CA_CERT	Optional	Path to the certificate for SSL connection verification. Specify if the PAM server uses a certificate signed by an internal CA. The certificate must be in PEM format. Example: ca_cert="/path/to/ca.crt". Default value: None.

Examples

ansible.cfg file

[pam]
idp_server = https://pam.company.com/idp
core_server = https://pam.company.com/core
username = my-app
password = your-app-password
timeout = 30
verify_ssl = true
ca_cert = /path/to/ca.crt

Environment variables

export PAM_IDP_SERVER="https://pam.company.com/idp"
export PAM_CORE_SERVER="https://pam.company.com/core"
export PAM_USERNAME="my-app"
export PAM_PASSWORD="your-app-password"
export PAM_VERIFY_SSL="true"    
export PAM_CA_CERT="/path/to/ca.crt"  
export PAM_TIMEOUT="30"        

Ansible playbook

- name: Retrieve password with explicit server specification
  ansible.builtin.set_fact:
    db_password: "{{ lookup('axidian.pam.get_password', 'SERVER/admin',
                            idp_server='https://pam.company.com/idp',
                            core_server='https://pam.company.com/core',
                            username='my-app',
                            password='app-password') }}"
  no_log: true

After configuring access, use plugins to retrieve credentials.

Plugins

Note

Use the no_log: true parameter to prevent credentials from being displayed in the console after the task is completed.

Ansible plugins are called through the lookup() function and allow you to retrieve the following from Axidian Privilege:

• account password
• account SSH key
• list of available accounts

get_password

The plugin is used to retrieve a PAM account password.

get_password parameters

Parameter	Requirement	Description
_terms	Required	Account name in the format: LOCATION/username — recommended format LOCATION\username — requires escaping in Python scripts, e.g. "SERVER\\admin" Passed as the second argument after the plugin name.
reason	Optional	Reason for retrieving credentials. Whether a reason is required is determined by the policy applied to the account.
errors	Optional	Error handling mode: strict — outputs an error and aborts task execution. Use when the scenario cannot proceed without the password. warn — outputs a warning and assigns an empty string to the variable. Use when the absence of a password does not affect the scenario. ignore — outputs no messages and assigns an empty string to the variable. Use when you handle errors yourself.

- name: Retrieve administrator password
  ansible.builtin.set_fact:
    admin_password: "{{ lookup('axidian.pam.get_password', 'PROD-SERVER/admin',
                               reason='Maintenance', errors='strict') }}"
  no_log: true

get_key

The plugin is used to retrieve a PAM account SSH key.

get_key parameters

Parameter	Requirement	Description
_terms	Required	Account name in the format: LOCATION/username — recommended format LOCATION\username — requires escaping in Python scripts, e.g. "SERVER\\admin" Passed as the second argument after the plugin name.
decrypt	Optional	Return the decrypted SSH key: True — return False — do not return Default value: True.
reason	Optional	Reason for retrieving credentials. Whether a reason is required is determined by the policy applied to the account.
errors	Optional	Error handling mode: strict — outputs an error and aborts task execution. Use when the scenario cannot proceed without the SSH key. warn — outputs a warning and assigns an empty string to the variable. Use when the absence of an SSH key does not affect the scenario. ignore — outputs no messages and assigns an empty string to the variable. Use when you handle errors yourself.

Response parameters

Parameter	Description
If decrypt=True in the request
key	Account SSH key in PEM format
If decrypt=False in the request
key	Encrypted SSH key
passphrase	Encrypted key passphrase

# Decrypted key (default)
- name: Deploy SSH key
  ansible.builtin.copy:
    content: "{{ lookup('axidian.pam.get_key', 'LINUX-SERVER/automation',
                               reason='Maintenance', errors='warn') }}"
    dest: /home/deploy/.ssh/id_rsa
    mode: '0600'
  no_log: true

# Encrypted key with passphrase
- name: Retrieve SSH key and its passphrase
  ansible.builtin.set_fact:
    ssh_creds: "{{ lookup('axidian.pam.get_key', 'LINUX-SERVER/automation',
                          decrypt=false) }}"
  no_log: true

get_accounts

The plugin is used to retrieve the list of available PAM accounts and does not require additional parameters.

Response parameters

The response contains a list of accounts in dictionary format with the parameters from the table.

Parameter	Description
display_name	Account name
requires_reason	Whether a reason for viewing credentials is required according to the policy: true — required false — not required

- name: Show available accounts
  ansible.builtin.debug:
    msg: "{{ lookup('axidian.pam.get_accounts') }}"

- name: Show account names only
  ansible.builtin.debug:
    msg: "{{ lookup('axidian.pam.get_accounts') | map(attribute='display_name') | list }}"

Using Ansible Vault

It is recommended not to store credentials in plain text and to encrypt them using the Ansible Vault component.

To encrypt the application password:

1. Open a terminal and run the command to encrypt the password:

   ansible-vault encrypt_string --ask-vault-pass '<password>' --name '<variable>'
   • password — the Axidian Privilege application password to encrypt
   • variable — the variable name for encryption

2. Enter the password that will be used to decrypt the variable when running the playbook.
   As a result, the encrypted variable will be displayed in the terminal.

3. Create a file in YAML or JSON format and save the command output to it.

   YAML

   vault_pam_password: !vault |
             $ANSIBLE_VAULT;1.1;AES256
             31643864386664376639656162346664313937633035346638656139376138656163376638656164
             6337663961383964666137633930626439656637666137660a313233343536373839306162636465

   JSON

   {
       "vault_pam_password": "$ANSIBLE_VAULT;1.1;AES256\n31643864386664376639656162346664313937633035346638656139376138656163376638656164\n6337663961383964666137633930626439656637666137660a31323334353637"
   }

4. Specify the variable in the playbook:

   • For the vars_files parameter, specify the path to the file containing the encrypted variable.
   • For the password parameter, specify the variable name.
     
     
   Example

   - name: Retrieve password using Vault
     hosts: localhost
     gather_facts: false
     vars_files:
       - ./vault.yml
     tasks:
       - name: Request account password from PAM
         ansible.builtin.set_fact:
           db_password: "{{ lookup('axidian.pam.get_password',
                                    'SERVER/admin',
                                    idp_server='https://pam.company.com/idp',
                                    core_server='https://pam.company.com/core',
                                    username='my-app',
                                    password=vault_pam_password) }}"
         no_log: true

Security Recommendations

1. Use the no_log: true parameter to prevent credentials from being displayed in the console when a task completes.
2. Do not store passwords in plain text — use Ansible Vault to encrypt credentials.
3. SSL connection verification is enabled by default. Disable it only for testing in isolated environments.
4. When running a scenario simultaneously on different hosts, it is recommended to include the host address in the connection reason. Example: reason='host={{ ansible_host }}; operation=maintenance'.