Table of Contents

  1. Overview
  2. Business Outcome
  3. Prerequisites
  4. Step 1: Setting Up the OAuth Consent Screen
  5. Step 2: Creating OAuth 2.0 Client IDs
  6. Step 3: Setting Up HashiCorp Vault
  7. Step 4: Enabling OIDC Authentication
  8. Step 5: Configuring the OIDC Role
  9. Step 6: Logging in with OIDC
  10. Conclusion

Overview

This blog post serves as a comprehensive guide to integrating Google Workspace as an OpenID Connect (OIDC) identity provider with HashiCorp Vault. By leveraging OIDC, organizations can streamline authentication for users accessing Vault, enhancing security and user experience. The guide provides detailed, step-by-step instructions covering the OAuth configuration in Google Workspace, setting up a Vault server in development mode, configuring OIDC authentication, and enabling the necessary callback URIs. The tutorial aims to simplify the process of implementing a secure, standards-compliant authentication method, making it easier for teams to authenticate and manage access to critical secrets in Vault.

Prerequisites

The administrator-level access to the organization’s Google Workspace account is required to create a new project, or permissions to create and configure OAuth 2.0 credentials for an existing project.

  1. In the Google Cloud console, go to menu > APIs & Services > OAuth consent screen.
  2. Select project, or create new project if does not have any. GCP console > choose project
  3. From the left navigation ment, select APIs and services > OAuth consent screen . GCP console > choose APIs
  4. In the user type for your app, choose “Internal”, then click Create. GCP console > choose Internal
  5. Complete the app registration form, then click Save and Continue.
  6. On the Scopes page leave everything blank and choose Save and Continue.

The OAuth consent screen for the selected project is now configured.GCP console > consent created

Step 2: Creates OAuth 2.0 Client IDs

1 In the Google Cloud consle, go to APIs & Services > Credentials.

  1. Choose “CREATE CREDENTIALS” from the top, and choose “OAuth client ID” GCP console > OAuth Client ID
  2. In the “Applcation type”, choose “Web application” GCP console > Web application
  3. Enter the client ID name.
  4. In the “Authorised redirect URIs”, add these 2 URI. Details of these 2 URIs can be found in Step 4
    1. http://localhost:8200/ui/vault/auth/oidc/oidc/callback
    2. http://localhost:8400/oidc/callback
  5. Choose “CREATE” GCP console > CREATE
  6. Screen showing that OAuth client created. Keep the screen open because we will need the information when creating the OAuth Auth for Vault GCP console > OAuth Client Created

Step 3: Setting up Hashicorp Vault

Note: In this tutorial, a localhost Vault will be used.

  1. Open a shell terminal, and starts the Vault server with command vault server -dev
  2. The following messages will show that the server is up 
     WARNING! dev mode is enabled! In this mode, Vault runs entirely in-memory
 and starts unsealed with a single unseal key. The root token is already
 authenticated to the CLI, so you can immediately begin using Vault.

 You may need to set the following environment variables:

     $ export VAULT_ADDR='http://127.0.0.1:8200'

 The unseal key and root token are displayed below in case you want to
 seal/unseal the Vault or re-authenticate.

 Unseal Key: <REDACTED>
 Root Token: hvs.<REDACTED>

 Development mode should NOT be used in production installations!
  3. Open another shell terminal, set the environment variable for the VAULT endpoint: 
     $ export VAULT_ADDR='http://127.0.0.1:8200'

Step 4: Enable OIDC Auth

  1. Keep the VAULT token as environment variable 
     $ export VAULT_TOKEN=hvs.<REDACTED>
  2. Enable OIDC auth for Vault 
     $ vault auth enable oidc
 Success! Enabled oidc auth method at: oidc/

Step 5: Setting up OIDC Role

  1. Create a role for the OIDC default role. Explainations of each parameter:
    1. The user_claim has to be either sub or email for Google Workspace queries to success.
    2. The two allowed_redirect_uris:
      1. http://localhost:8250/oidc/callback is a temporary local webserver on port 8250 to receive a redirect to localhost, when vault login -method=oidc is being executed.
      2. ${VAULT_ADDR}/ui/vault/auth/oidc/oidc/callback is the callback from Google Workspace with the token
    3. user_claim is to uniquely identify the user.
    4. groups_claim is to to uniquely identify the set of groups to which the user belongs.
    5. verbose_oidc_logging Log received OIDC tokens and claims if the non-production server was started with export VAULT_LOG_LEVEL=debug. 
       $ vault write auth/oidc/role/default \
 user_claim="email" \
 groups_claim="groups" \
 allowed_redirect_uris=http://localhost:8250/oidc/callback,${VAULT_ADDR}/ui/vault/auth/oidc/oidc/callback \
 verbose_oidc_logging=true
 Success! Data written to: auth/oidc/config
  2. Configure the Vault OIDC auth with Google OIDC information. Reference to the screen, the mapping as followings: GCP console > OAuth client created
    • oidc_discovery_url=”https://accounts.google.com”
    • oidc_client_id=”Client ID”
    • oidc_client_secret=”Client Secret” 
       vault write auth/oidc/config \
 oidc_discovery_url=https://accounts.google.com \
 oidc_client_id=<MASKED>.apps.googleusercontent.com \
 oidc_client_secret=GOCSPX-<MASKED>mpHMn \
 default_role=default

Step 6: Login with OIDC

  1. Login with OIDC method.

    1. The port=8250 is the local server that vault login creates for the Google Workspace will redirect to. ``` % vault login -method=oidc port=8400 role=default Complete the login via your OIDC provider. Launching browser to:

      https://accounts.google.com/o/oauth2/v2/auth?client_id=630608949624-tb6c9lhieuotajo4r8oe0to0ek42nul7.apps.googleusercontent.com&code_challenge=D4VghdGdyoC-8Uaz8BMvictrP3pyDIV6TbmaQAdHkuY&code_challenge_method=S256&nonce=n_TB7BCUd8bzMpm8KSnZxL&redirect_uri=http%3A%2F%2Flocalhost%3A8400%2Foidc%2Fcallback&response_type=code&scope=openid+email+profile&state=st_jIhTjKFTbVMs8k8aoHbb

    Waiting for OIDC authentication to complete… ```

  2. A browser should pop up for the Google login
  3. Once browser login successful, the vault will display the token: 
     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
 ---                  -----
 token                hvs.<OIDC TOKEN>
 token_accessor       <REDACTED>
 token_duration       768h
 token_renewable      true
 token_policies       ["default"]
 identity_policies    []
 policies             ["default"]
 token_meta_role      default

Note: If the port mismatch with OAuth callback, Google workspace will throw Error 400: GCP console > error 400

Conclusion

Configuring Google Workspace as an OpenID Connect (OIDC) provider for HashiCorp Vault enhances the security, scalability, and usability of your organization’s authentication processes. By following the steps outlined, teams can leverage Google’s identity management to streamline secure access to Vault, reducing the risks associated with multiple credentials and manual access controls. This setup allows organizations to provide consistent, controlled access to sensitive data while integrating seamlessly with existing identity providers. Adopting OIDC with Vault not only strengthens compliance and security but also promotes operational efficiency, empowering teams to focus on core tasks within a unified, secure infrastructure.