Identity based SSH with Vault and Keycloak. | Part 1/3
Step by Step Guide for Configuring Vault + KeyCloak OIDC
Part 1 of the comprehensive guide which focuses on individual aspects of the overall configuration. Following is the brief of what each part focuses on:
- Part 1 — Step by Step Guide for Configuring Vault + KeyCloak OIDC
- Part 2 — Step By Step Guide for Configuring Vault SSH Secrets engine for Signed SSH Certificates
- Part 3 — Step By Step Guide for Configuring Vaut SSH Secrets engine for SSH OTP. (coming soon)
You are using SSH, but are you using it right? Probably not! Chances are that you are using password based authentication or private key based authentication to access your servers. Although necessary to provide administrative access, these methods are non-reliable and insecure at scale.
Private Key based authentication is still widely popular, but many processes, applications and users access the servers, so that will end up with a long list of public keys in the authorized_keys file of the server and it grows till it gets unmanageable, cleaned up and populated again. There’s need for an SSH Solution that is Dynamic, Scalable and Secure, something that uses Identity to Authenticate User, and authorize access against a set of policies, and most importantly, log the activity. We are going to use Hashicorp Vault to provide Authenticatation and Authorization user for SSH access, and Keycloak to demonstrate OIDC integration with Vault.
Use of identity to authorize SSH access will make it scalable and secure. You can simply allow/revoke access to set of servers by applying required set of policies to user, or simply delete the user when they leave the organization. It makes on-boarding of users even easier.
No more dangling private keys and long list if authorized public keys.
Vault is a powerful secret management tool by Hashicorp, it provides api’s and tooling to store, manage and generate secrets securely. Its has built in secret engines for wide range of applications and services. SSH is one such powerful engine that we are going to use to dynamically generate signed certificates and OTP to access our SSH Hosts.
KeyCloak or its enterprise downstream RedHat SSO is a powerful Identity Provider and Single Sign On Server by RedHat. Its found to be used by many large enterprises such as SalesForce for providing User Management, Authentication and Federation, including RedHat itself. We are going to use it to demonstrate OIDC authentication for vault.
For this setup we are going to use vagrant to provision VM’s for Vault and SSH Host. Please make sure you have necessary packages installed for it to work.
Clone this demo repository to setup the test environment.
Start Vagrant Machines:
Go to the cloned directory and run vagrant up
cd vault-ssh && vagrant up
This will provision the VM’s for Vault Server, and 2 SSH Hosts.
- 192.168.56.101 — Vault Server
- 192.168.56.102 — Host 1
- 192.168.56.103 — Host 2
Configure Vault Server
Vault UI will be accesible on https://192.168.56.101:8200/ui , open it in browser to proceed with configuration.
On opening the ui for first time you’ll be taken to initialization page. Here you’ll need to generate master keys and root token. After initialization, vault is sealed, and Master Key Shares will be used to unseal it. Options are as following.
- Key Shares: Number on Key Share to Split Master Key into.
- Key Threshold: Number of unique key shared required to unseal vault. Cannot be greater than the number of Key Shares.
For our demo we’ll set both values to
1 . After clicking on
Initialize masked Initial root token, and Master Keys will be displayed. Click on
Download keys to download the json file containing keys and root token.
Now we can proceed to unseal Vault using the key in the downloaded json.
Click on Continue to Unseal and Copy the master key part under the
keys block in json.
In the next step use the root_token to sign in to vault.
Initialize KeyCloak Server
KeyCloak Server is available at http://192.168.56.101:8080, open it in browser to login. Username and Password combination is
- Configure Vault Client in KeyCloak:
Download the vault.json file containing client configuration from here.
In KeyCloak Admin Console, Goto Clients > Create . Import the downloaded vault.json to configure the vault OIDC client in KeyCloak.
2. Create a test user ‘testing’ in Keycloak:
Go to Users and click on add user, and create configure the user as follows:
- Username: testing
- Email: firstname.lastname@example.org
- First Name: Test
- Last Name: User
- User Enabled: On
- Email Verified: On
Then go to the Credentials tab for the created user, and Set a new password for user i.e
testing123 and set ‘Temporary’ to ‘OFF’. We’ll use this user to login to vault using oidc method.
Create Admin Policy on Vault:
Access Vault Server and Login to Vault CLI:
Get SSH Console into vault server vagrant machine by running
vagrant ssh vault
VAULT_SKIP_VERIFY environment to skip tls verfication as we are using self signed TLS certificate in our demo environment.
add it to
~/.bashrc to set it automatically on startup. Now proceed with vault cli login. Use the vault root token generated during init.
echo $VAULT_TOKEN | vault login -Success! You are now authenticated. The token information displayed below
is already stored in the token helper. You do NOT need to run "vault login"
again. Future Vault requests will automatically use this token.Key Value
Create Admin Policy:
Run the following command to create the admin policy, which we’ll use as default in our oidc configuration
vault policy write admin /vagrant/admin.hcl
Success! Uploaded policy: admin
Configure OIDC Auth:
- Enable OIDC Auth Method:
vault auth enable oidc
2. Set KC_DOMAIN, KC_CLIENT_ID and KC_CLIENT_SECRET to configure oidc_discovery_url , oidc_client_id and oidc_client_secret respectively:
- To get values for KC_CLIENT_ID and KC_CLIENT_SECRET from KeyCloak vault client we previously created:
- For KC_CLIENT_ID, goto clients > vault > settings tab, and copy the client id
- For KC_CLIENT_SECRET, goto clients > vault > credentials tab, and copy the Secret
- Once the variables are set run:
vault write auth/oidc/config \
3. Now we’ll create the default role for oidc
export VAULT_CLI=https://127.0.0.1:8250vault write auth/oidc/role/default \
4. Once that is done we’ll use oidc to login to vault ui.
Open vault ui at https://192.168.33.11:8200/ui, under Method drop-down select ‘OIDC’, leave Role blank and we are assiging default role, and click Sign In. You will be redirected to Keycloak Login Page, enter your credentials here, and Login.
Upon successful login, you will be taken to vault and logged as OIDC user testing, with admin policy attached which we have attached with the default OIDC Role. To know much more about Vault OIDC auth check this link.
Now that we are able to Successfully Login to Vault using KeyCloak, let’s conclude this guide, work is in progress for Part 2, will be soon publishing it.