Setup guide Keycloak as an Identity Provider (IdP) for HashiCorp Vault

Setup guide Keycloak as an Identity Provider (IdP) for HashiCorp Vault

Setting up Keycloak as an Identity Provider (IdP) for HashiCorp Vault requires a series of steps. Here's a step-by-step guide to help you configure Keycloak with Vault:

Deploy Keycloak in a docker

here is a docker-compose to deploy keycloak in your lab

version: '3'

    image: jboss/keycloak:latest
      - KEYCLOAK_USER=admin
      - DB_ADDR=postgres
      - DB_DATABASE=keycloak
      - DB_USER=keycloak
      - DB_PASSWORD=password
      - "8080:8080"
      - postgres

    image: postgres:latest
      - POSTGRES_DB=keycloak
      - POSTGRES_USER=keycloak
      - POSTGRES_PASSWORD=password
      - postgres_data:/var/lib/postgresql/data


1. Install and Configure Keycloak

  • Install Keycloak: If you haven't already, install Keycloak. You can find installation guides on the Keycloak website.

  • Set Up a Realm: In Keycloak, create a new realm or use an existing one for Vault.

  • Create a Client: Create a new client in Keycloak for Vault. Set the "Access Type" to "confidential" and note down the client ID and secret.

    1. Select/create a Realm and Client. Select a Client and visit Settings.

    2. Client Protocol: openid-connect

    3. Access Type: confidential

    4. Standard Flow Enabled: On

    5. Configure Root URL such as

    6. Configure Valid Redirect URIs such as

    7. Save.

    8. Visit Credentials. Select Client ID and Secret and note the generated secret.

2. Configure Client in Keycloak

  • Set Valid Redirect URIs: In the client settings, specify the redirect URI. This URI is where Vault will receive authentication responses from Keycloak. It typically follows the pattern http://<Vault_Address>/ui/vault/auth/oidc/oidc/callback or http://<Vault_Address>/v1/auth/oidc/oidc/callback depending on your setup.

  • Configure Client Scopes and Mappers: You may need to configure client scopes and mappers in Keycloak to pass the correct claims to Vault.

3. Enable and Configure OIDC Auth Method in Vault

  • Enable OIDC Auth Method: On the Vault server, enable the OIDC authentication method using a command like:

      vault auth enable oidc
  • Configure OIDC with Keycloak Details: Configure the OIDC auth method with the details from Keycloak. Use the following command but replace placeholders with your actual data:

      vault write auth/oidc/config \
          oidc_discovery_url="https://<Keycloak_domain>/auth/realms/<realm_name>" \
          oidc_client_id="<client_id>" \
          oidc_client_secret="<client_secret>" \

4. Define Roles in Vault

  • Create Vault Policies: Define policies in Vault that will be assigned to authenticated users.

  • Create Vault Roles: Map Keycloak groups or claims to Vault roles. For each role, you specify the bound claims and the policies that apply. Example:

      vault write auth/oidc/role/<role_name> \
          user_claim="sub" \
          allowed_redirect_uris="http://<Vault_Address>/ui/vault/auth/oidc/oidc/callback" \

5. Test the Authentication

  • Log In Using Keycloak: Try logging into Vault using Keycloak credentials to test the setup. You can do this through the Vault UI or via the CLI.

6. Additional Configuration (Optional)

  • Group Mapping: If you want to map Keycloak groups to Vault policies, you might need to configure additional claims in Keycloak and roles in Vault.

  • Fine-Tuning: Depending on your needs, you might want to fine-tune the token settings, role mappings, and other configurations in both Keycloak and Vault.

7. Secure Your Setup

  • SSL/TLS: Make sure both Keycloak and Vault are using SSL/TLS to secure their communications.

  • Review Security Settings: Regularly review and update your security settings in both Keycloak and Vault.

Documentation and Resources

This guide provides a general overview, and you may need to adjust the steps based on your specific environment and requirements.

Did you find this article valuable?

Support Sebastian Maniak by becoming a sponsor. Any amount is appreciated!