Sam Doran

My little corner of the Internet

Ansible Vault and macOS Keychain Access

A little known feature of Ansible Vault is the ability to use a script as the Ansible Vault password file.

Alternately, you may specify the location of a password file or command Ansible to always prompt for the password in your ansible.cfg file.

I work on many Ansible projects, each using separate Ansible Vault keys. It became very tedious to enter the password on the command line every time and I really don’t like storing keys unencrypted on disk.1 Luckily, macOS, my development platform of choice, has a built in system keychain as well as a command line tool for retrieving things from it.

I wrote a script that would retrieve the appropriate Ansible Vaulte key from the macOS system keychain based on my current working directory. This allows me to set my vault_password_file once in the Ansible config (or you could use the ANSIBLE_VAULT_PASSWORD_FILE environment variable) and it will always get the correct key based on the current project I’m working on and fall back to a default key.

The first step is to store the keys in Keychain Access2. Open Keychain Access and click File > New Password Item…. You’ll be prompted to enter three bits of information: the Keychain Item Name, Account Name, and Password.

Keychain Item Name is what is displayed in Keychain Access when looking at things and searching. I prefer to name everything “Ansible Vault [project name]” so I can easily find all my Ansible Vault keys simply by searching for “Ansible Vault.”

Account Name is the name you will pass to the security command line tool in order to retrieve the password. Since this is a command line parameter, I like to keep it all lowercase without spaces. I just use the lowercase name of the project I’m working on.

Lastly, put the Ansible Vault key in the password field. It should look something like this when you’re done:

Naming them this way makes it easy to find all your Ansible Vault keys with a simlpe search.

And here is the script:

In order for Ansible to use this, you must make it executable by using chmod +x getvaultkey.sh and set vault_password_file in your ansible.cfg or the ANSIBLE_VAULT_PASSWORD_FILE environment variable to the script location. It doesn’t need to be in your PATH. I like to keep my scripts in ~/bin, which is in my PATH just so things stay tidy.

You can customize the script to add additional case statements based on the paths of projects you are working on. Essentially this is constructing a single command that when run will print out a password and only a password3.

Note that the first time you run this script, macOS will prompt you for your password. This is a security mechanism to prevent malicious code from silently grabbing things out of your unlocked keychain without your knowledge. You will have to authorize each password stored in Keychain Access but only the first time

Hopefully this will make using Ansible Vault on macOS much easier.


  1. I encrypt the entire disk using FileVault, so technically everything is encrypted at rest. But with security, you can’t have too many layers of protection.

  2. I keep everything in [1Password][], including my Ansible Vault keys, so I have to create a second copy in Keychain Access.

  3. In Ansible 2.4, [Ansible Vault got a big upgrade][ansiblevault24] with regards to vault keys, but this should still work for the foreseeable future.