Remote Deployment of Windows User-ID Agent using Ansible
Resolution
Ansible is a configuration management tool typically used to enforce the state of a server in your IT infrastructure. It is used to ensure that the server is indeed in the same state as you would want it to be. It ensures the right packages are installed, the right configuration files are in place, right services are running with the right permissions ...etc.
Administrators write set of rules in a simple language (YAML), in the form of playbooks. Ansible works by connecting to your nodes and pushing out small programs, called "Ansible modules" to them. More details on how Ansible works can be found here
Administrators could use Windows Ansible Modules (http://docs.ansible.com/ansible/latest/list_of_windows_modules.html) and remotely install and manage User-ID Agent (Palo Alto Networks Admin Guide)
Ansible by default uses SSH to manage Linux. To manage Windows, PowerShell remoting is used. For ansible to manage Windows machines, the steps documented in Ansible site needs to be followed
Reference: http://docs.ansible.com/ansible/latest/intro_windows.html
The following steps showcases some of the Windows Ansible Modules that where used to write Ansible Playbook to remotely deploy User-ID Agent.
Ansible works against multiple systems in your infrastructure at the same time. It does this by selecting portions of systems listed in Ansible’s inventory, which defaults to being saved in the location /etc/ansible/hosts
For example, I have defined a User-ID Agent server (uid1.palab.local) under a tag (windows)
[windows] uid1.palab.local
The following module installs User-ID Agent on Windows Server. Details on win_package module can be found here
In the below example, the User-ID Agent installer (*.msi), is hosted on a network share.
- hosts: windows tasks: - name: Install UID win_package: path: \\DC1\Users\Administrator\Downloads\UaInstall-8.0.7-2.msi product_id: User-ID Agent state: present user_name: PALAB\Administrator user_password: MySuperSecretPass
The following command would execute the playbook:
ansible-playbook -vvv install_uid.yml
Ansible comes with a tool called as Ansible Vault (vault link) to encrypt secrets. These secrets can then be used in tasks.
Create a secret.yml file.
--- mysecret: MySuperSecretPass
Encrypt the secret.yml file
# ansible-vault encrypt secret.yml New Vault password: EnterASuperSecretPass Confirm New Vault password: EnterASuperSecretPass Encryption successful
Contents of the secret.yml file will be encrypted and will look as shown below (contents will be different in your environment)
cat secret.yml $ANSIBLE_VAULT;1.1;AES256 63303662393262633865366536333531383362633838316462313739306431656130383730303036 6433623639316439313565393430333430643930623266350a353533666432613438626331396636 32326366386361363363383335333135386364346466636533353434323261373739363533626238 3635613765383762380a306439383961336261316432376266386338643765313064376264633535 35616534613264353739333564633534353230623630653762373632323766643838
The variable (for example: mysecret) defined in secret.yml could now be used in the playbooks as follows:
- hosts: windows tasks: - name: Install UID win_package: path: \\DC1\Users\Administrator\Downloads\UaInstall-8.0.7-2.msi product_id: User-ID Agent state: present user_name: PALAB\Administrator user_password: "{{mysecret}}"
To execute the above playbook, you would enter the folllowing command:
root@kali:/etc/ansible# ansible-playbook --ask-vault-pass install_uid_vault.yml Vault password: EnterASuperSecretPass
Refer http://docs.ansible.com/ansible/latest/playbooks_vault.html for more details on Vault.
Note: If a dedicated service account is used for User-ID Agent, additional steps need to be performed on the windows server (such as assign account permissions to the installation folder, modify User-ID agent registry permissions ...etc). Refer to admin guide to give the right permissions.
The following ansible module can be used to change permissions on the remote User-ID agent servers. In the below example, a service account (uidagent@palab.local) has been created for User-ID agent to use.
- hosts: windows tasks: - name: set the permissions of the folder win_acl: path: C:\Program Files (x86)\Palo Alto Networks rights: FullControl type: allow state: present inherit: ContainerInherit, ObjectInherit propagation: 'None' user: uidagent@PALAB.LOCAL - name: set registry key right win_acl: path: HKLM:\Software\Wow6432Node\Palo Alto Networks user: uidagent@PALAB.LOCAL rights: FullControl type: allow state: present inherit: ContainerInherit, ObjectInherit propagation: 'None'
Module to set Logon as a Service with the service account
- hosts: windows tasks: - name: set the logon user to a domain account win_service: name: User-ID Agent state: restarted username: uidagent@PALAB.LOCAL password: MySuperSecretUIDPass
Before deploying other User-ID agents, configure User-ID one of the windows server (let us call it the master Windows server). We will copy the configurations from the master Windows server and deploy it on other servers.
Follow the steps (Admin Guide) to configure User-ID agent on master windows server. Once the configurations are complete, "UserIDAgentConfig.xml" file will be written to the User-ID installation folder. Copy the UserIDAgentConfig.xml file to your ansible controller. Check (Optional) section below if you are assigning a custom certificates for the User-ID agent to authenticate to the firewall. Once those steps are complete, copy the "UserIDAgentConfig.xml" file.
root@ansible:/etc/ansible# cd files/ root@kali:/etc/ansible/files# ls -ltr UserIDAgentConfig.xml -rw-r--r-- 1 root root 4559 Mar 14 12:01 UserIDAgentConfig.xml
(Optional):
To authenticate SSL connections between firewall and the User-ID agent, administrators can upload custom certificates on the User-ID Agent.
To enable mutual authentication between firewall and User-ID Agents, perform the following steps on a Master Windows server and use the configurations from that server and remotely push to other servers.
- Install User-ID Agent on a master Windows Server
- Perform relevant User-ID agent configurations
- Upload custom certificates on that server.
- Save the configuration
- Do Not commit the configuration
- Copy the UserIDAgentConfig.xml from the Windows Server to Ansible controller
- If multiple User-ID agents have to be remotely configured this way, go to step 3, and, upload the relevant User-ID agent certificate. Perform Step 4, 5 and 6.
Module to copy the "UserIDAgentConfig.xml" file to remote servers.
"win_copy" (link) is used to copy the configuration file to User-ID Agent installation folder on the remote Agent Servers. For example, you will use the command "ansible-playbook -vvv copy_uid_config.yml" to execute the following task.
- hosts: windows tasks: - name: Copy a single file keeping the filename win_copy: src: UserIDAgentConfig.xml dest: C:\Program Files (x86)\Palo Alto Networks\User-ID Agent\
User-ID Agent can be upgraded using the same module used to install User-ID. Just change the installer file
- hosts: windows tasks: - name: Install UID win_package: path: \\DC1\Users\Administrator\Downloads\UaInstall-8.1.0-66.msi product_id: User-ID Agent state: present user_name: PALAB\Administrator user_password: MySuperSecretPass
Once the upgrade is complete, the User-ID agent service needs to be restarted.
Using the "win_service" module (link), we can restart the User-ID Agent service.
- hosts: windows tasks: - name: restart service win_service: name: User-ID Agent state: restarted
On the firewall, you can note that the Connection Security has been configured under (Device > User Identification > Connection Security). In this step, the firewall verifies the CA Certificate that signed the User-ID Agent's certificates.
Miscellaneous:
The ignore user list defines which user accounts don’t require IP address-to-username mapping (for example, kiosk accounts). More details can be found in the Admin Guide
Create an ignore list file in ansible controller (name the file as ignore_user_list.txt)
root@ansible:/etc/ansible# cat files/ignore_user_list.txt palab\administrator
Send the ignore list to remote User-ID agent servers. This file will be copied to installation folder. "win_copy" Ansible Windows module will be used to achieve this task.
- hosts: windows tasks: - name: Copy a single file keeping the filename win_copy: src: ignore_user_list.txt dest: C:\Program Files (x86)\Palo Alto Networks\User-ID Agent\
For the ignore list to take effect, the User-ID agent service has to be restarted. Use the recipe provided earlier to restart the User-ID agent service.
Before application of ignore list:
After application of ignore list:
Use the above guide at your own risk: The steps outlined reflect a setup we conducted in a lab environment.
Results and configuration parameters may vary depending on your environment and should be reviewed and tested before deploying in production.