Setup

TL;DR: Get me started quickly / Creating your initial setup

To get things set up, you need to look at the 'global_vars.yml' file and set the variables to match your environment. First install the install the Keycloak server if you haven't got one yet. Define your own 'realm' in keycloak (using the GUI) and enter the name in the 'global_vars.yml´ file.

Edit the encrypted-vars.yml file and change the settings to make your environment. See below for the mandatory contents.

Do the same for the 'global-vars.yml' file.

Check if your Linunx distribution has the excellent 'mkcert' program in its repositories. If not, download 'mkcert' from here. and put it in the 'files' subdirectory.

**A lot of Keycloak installation assume you proxy the "/auth" url to the Keycloak back-end. We don't. So take this into account when reading online about Keycloak Url' starting with "/auth"

A lot of applications expect SSL connections between SP (the application providing a service) and the Idp (server doing the identity checks). Some people are really good in working with OpenSSL in the command line. I'm not one of this people. But the 'mkcert' project is a brilliant tool for this. Please see the mkcert project page on Github for more info.

Basically what you do is:

 $ # Setup the mkcert program after downloading.
 $ mkcert -install
 $ # Have mkcert create a root CA for signing your keys.
 $ mkcert -CAROOT
 $ # Have mkcert create a 'wildcard' ssl certificate
 $ mkcert "*.your-internal-network-name.lan"
 $ # Now upload the results using the install-ssl-infra.yml playbook.

The rest of the page talks about Ansible vault and how to secure passwords. If you know this already, you can skip this page.

Needed extra files.

You will need your own version of encrypted-vars.yml. It's contents similar to this:

# Keycloack
kc_adminid: admin
kc_adminpw: very_secret_password
 
# BitWarden
bw_installation_id: some_weird_string
bw_installation_key: some_other_weird_string

You will also need your own version of global-vars.yml. It's contents similar to this:

ansible_python_interpreter: /usr/bin/python3
keycloak_server_url: https://kc.your-domain.tld
realm: my_realm
domain: my-domain.lan  
timezone: Europe/Amsterdam
root_ca_path: /usr/local/share/ca-certificates/mkcert_development_CA_62225839681785622328732999788222374785.crt

# If you are using Bitwarden
bw_organization_name: "Organizationname"
# The following id is probably the same as your organization name.
bw_organization_id: "Organizationname"

Getting started with vault

Ansible vault is a mechanism to store passwords in an encrypted file. You can only edit or use the contents of this file if you know the password with which this password 'vault' was initially created.

Creating a small vault

The file we are using here is named 'encrypted-vars.yml'. It is created with the commando:

$ ansible-vault create encrypted-vars.yml
New Vault password:
Confirm New Vault password:

Then an editor session is opened where you can enter the passwords you are using.

Since we are using Keycloak as the identity provider for this project we store the admin userid and password for keycloak here. If you are also setting up Bitwarden SSO, you will need the Bitwarden installation_id and installation_key. So, as an example, the contents of this file could look like this:

# Keycloack
kc_adminid: admin
kc_adminpw: very_secret_password
 
# BitWarden
bw_installation_id: some_weird_string
bw_installation_key: some_other_weird_string

When you have entered this you can save and close this file.

Editing the vault

Editing this vault file at any later time is very simple and easy:

$ ansible-vault edit encrypted-vars.yml
Vault password:

When you enter the correct password the editor will start and you can edit to your heart's content.

Using the vault with a playbook

In your Ansible playbook you add the following text:

- name: Read encrypted content
  include_vars: encrypted-vars.yml

This will trigger Ansible to try to load the contents of this file.

If you do not supply a password this is where the play will end:

TASK [Read encrypted content] 
fatal: [cmdb]: FAILED! => {
   "ansible_facts": {},
   "ansible_included_var_files": [],
   "changed": false,
   "message": "Attempting to decrypt but no vault secrets found"
}

You can tell Ansible that you would like to be asked for the password:

$ ansible-playbook  playbook.yml -i hosts  --ask-vault-pass
Vault password:

Using the vault in a user friendly way

Since entering the vault password every time can be tiresome, it is also possible to point to a file containing the password:

First create a file '.vault-password' and put the password in it. Now run Ansible and point to this file:

$ ansible-playbook playbook.yml -i hosts  --vault-password-file .vault-password

TASK [Read encrypted content] 
ok: [myhost]

If your playbooks are in a git repository ()and why wouldn't they be?) PLEASE add this file to the '.gitignore' file so you will not accidentaly add and push the contents of your password file to your repository!

$ cat .gitignore
.vault-password

Additional reading

• Ansible page about vault