Configure HashiCorp Vault as a vault backend with OAuth2

To use OAuth2 authentication for your HashiCorp Vault with Auth0 as the identity provider (IdP), there are two important configurations to prepare in Auth0. First, you must authorize an Auth0 application so Kong Gateway can use the Auth0 Management API on your behalf. Next, you will create an API audience that Kong Gateway applications will be granted access to.

To get started configuring Auth0, log in to your Auth0 dashboard and complete the following:

1. From the sidebar, select Applications > Applications.

2. Click Create Application.

3. Give the application a memorable name, like “HashiCorp Vault OAuth2”.

4. Select the application type Machine to Machine Applications and click Create.

5. Select Auth0 Management API from the drop-down list.

6. In the Permissions section, select the following permissions to grant access, then click Authorize:
   • read:client_grants
   • create:client_grants
   • delete:client_grants
   • update:client_grants
   • read:clients
   • create:clients
   • delete:clients
   • update:clients
   • update:client_keys

   Note: If you’re using Developer Managed Scopes, add read:resource_servers to the permissions for your initial client application.

7. Click Authorize.

8. On the application page, click the Settings tab, locate the values for Domain, Client ID and Client Secret, and export them as environment variables:

   export DECK_DOMAIN="YOUR AUTH0 DOMAIN"
   export DECK_CLIENT_ID="YOUR AUTH0 CLIENT ID"
   export DECK_CLIENT_SECRET="YOUR AUTH0 CLIENT SECRET"
   

   Copied!

Important: This tutorial uses the literal root string as your token, which should only be used in testing and development environments.

1. Install HashiCorp Vault.
2. In a new terminal, start your Vault dev server with root as your token.

   vault server -dev -dev-root-token-id root
   

   Copied!
3. In the output from the previous command, copy the VAULT_ADDR to export.
4. In the terminal window where you exported your Auth0 variables, export your VAULT_ADDR as an environment variable.
5. Verify that your Vault is running correctly:

   vault status
   

   Copied!
6. Enable JWT and add the Auth0 JWKS URL:

   vault auth enable jwt
   vault write auth/jwt/config jwks_url="https://$DECK_DOMAIN/.well-known/jwks.json"
   

   Copied!
7. Configure a JWT role named demo:

   vault write auth/jwt/role/demo \
    role_type=jwt \
    user_claim=sub \
    token_type=batch \
    token_policies="default" \
    bound_subject="$DECK_CLIENT_ID@clients" \
    bound_audiences="https://$DECK_DOMAIN/api/v2/"
   

   Copied!
8. Add a secret:

   vault kv put -mount="secret" "password" pass1=my-password
   

   Copied!
9. Export the HashiCorp host and token to your environment:

   export DECK_HCV_HOST=host.docker.internal
   export DECK_HCV_TOKEN=root
   

   Copied!

   In this tutorial, we’re using host.docker.internal as our host instead of the localhost variable that HashiCorp Vault uses by default. This is because if you used the quick-start script Kong Gateway is running in a Docker container and uses a different localhost. Because we are running HashiCorp Vault in dev mode, we are using root for our token value.

1. Navigate to http://localhost:8200/ to access the HashiCorp Vault UI.

2. Enter “root” in the Token field and click Sign in.

3. Click Policies.

4. Click default.

5. Click Edit policy and append the following to the policy file:

   path "secret/*" {
    capabilities = ["read"]
   }
   

   Copied!
6. Click Save

Create a Vault entity with the required parameters for HashiCorp Vault:

echo '
_format_version: "3.0"
vaults:
  - name: hcv
    prefix: hashicorp-vault
    description: Storing secrets in HashiCorp Vault
    config:
      host: "${{ env "DECK_HCV_HOST" }}"
      token: "${{ env "DECK_HCV_TOKEN" }}"
      kv: v2
      mount: secret
      port: 8200
      protocol: http
      auth_method: oauth2
      oauth2_role_name: demo
      oauth2_token_endpoint: https://${{ env "DECK_DOMAIN" }}/oauth/token
      oauth2_client_id: "${{ env "DECK_CLIENT_ID" }}"
      oauth2_client_secret: "${{ env "DECK_CLIENT_SECRET" }}"
      oauth2_audiences: https://${{ env "DECK_DOMAIN" }}/api/v2/
' | deck gateway apply -

export KONNECT_DP_CONTAINER='your-dp-container-name'

To validate that the secret was stored correctly in HashiCorp Vault, you can call a secret from your vault using the kong vault get command within the Data Plane container.

docker exec $KONNECT_DP_CONTAINER kong vault get {vault://hashicorp-vault/password/pass1}

docker exec kong-quickstart-gateway kong vault get {vault://hashicorp-vault/password/pass1}

If the vault was configured correctly, this command should return the value of the secret. You can use {vault://hashicorp-vault/password/pass1} to reference the secret in any referenceable field.

For more information about supported secret types, see What can be stored as a secret.