Configuring an OIDC Auth Method with HCP Vault

Introduction

In this article, we will go over how to setup OIDC auth method within HCP Vault with specific examples for HCP Vault clusters. This guide follows closely with the HashiCorp Learn Guide OIDC Auth Method.

The example OIDC method used in this article is Google OIDC.

Prerequisites

• HCP Vault cluster
• Google Cloud Platform Account

Steps

PLEASE NOTE: For full explanation of the steps to setup HashiCorp Learn Guide OIDC Auth Method please follow the official learn guide. The following steps are condensed and used to point out specific parts of the official learn guide that concerns HCP Vault settings and configuration.

1. Access your HCP Vault cluster via CLI. Please ensure to export the VAULT_NAMESPACE variable in order to ensure that the commands will work with HCP Vault. Alternatively, you can set up the OIDC auth method via the HCP Vault UI.

   • export VAULT_ADDR="<YOURVAULTCLUSTER>"; export VAULT_NAMESPACE="admin"
     
     vault login <YOURADMINTOKEN>

2. Set up the OIDC method

   • vault auth enable oidc

3. Configure the OIDC config. This example sets the default role to "gmail". Please refer to these instructions on how to gather the credentials needed for the Google OIDC config.

   • vault write auth/oidc/config \
         oidc_discovery_url="https://accounts.google.com" \
         oidc_client_id="OIDC_CLIENT_ID" \
         oidc_client_secret="OIDC_CLIENT_SECRET" \
         default_role="gmail"

4. Configure the OIDC role. This example attaches an existing policy called "admin". You must create a new policy or attach an existing policy to the role.

   • vault write auth/oidc/role/gmail \
         user_claim="sub" \
         bound_audiences="OIDC_CLIENT_ID" \
         allowed_redirect_uris="$VAULT_ADDR/ui/vault/auth/oidc/oidc/callback" \
         allowed_redirect_uris="http://localhost:8250/oidc/callback" \
         policies=admin

     • NOTE: The https://localhost:8250/oidc/callback address enables the Vault CLI to login via the OIDC method.

5. Login via the HCP Vault Cluster UI or via CLI

   • vault login -method=oidc role=gmail

Limitations and Known Issues

Custom Paths for OIDC auth method

If you would like to set a custom OIDC auth mount path, it is important to both specify the path when enabling the auth method as well as change the OIDC callback URLs to include the new custom path.

vault auth enable -path=custompath oidc

vault write auth/custompath/role/gmail \
    user_claim="sub" \
    bound_audiences="OIDC_CLIENT_ID" \
    allowed_redirect_uris="VAULT_ADDR/ui/vault/auth/custompath/oidc/callback" \
    policies=admin

When logging in with custom path via CLI, use a command similar to the following:

vault login -method=oidc -path=custompath role=gmail

In order to specify a custom mount path in the HCP Vault UI, click to expand "More options" option and enter your custom mount path.

Google Workspaces

If trying to set the gsuite_service_account variable for the Optional Google-specific Configuration, you will not be able to provide a path to a file since HCP Vault does not allow you to add files directly to the HCP Vault cluster. As a workaround, please provide a string directly with the JSON contents. The JSON must be properly escaped.