OIDC authentication with Google Workspace

8min
|
HCP
Vault

Before a client can interact with Vault, it must authenticate with an auth method to acquire a token.

This token has policies attached so that the behavior of the client can be governed.

Note

To learn the basics of Vault tokens, go through the Tokens tutorial.

Auth methods perform authentication to verify the user or machine-supplied information. Some auth methods are targeted towards users while others are targeted toward machines or apps.

Challenge

Vault supports a number of auth methods for users or system to prove their identity so that a token with appropriate policies can be obtained. Delegated authorization methods based on OAuth 2.0 are convenient for users and have become increasingly common.

Solution

Google Workspace is a good option for small or medium-sized organizations that would like to use Google as a Single Sign-on Provider to authenticate to Vault.

If you use Google Workspace (AD), you can use Google Workspace Single Sign-on to verify the identity of a Vault user. By registering a Vault application in Google Workspace, and configuring Vault's OIDC auth method, your Vault users can log into Vault using a web browser. They will be redirected to Google to complete the login and then be routed back to Vault with a newly-created token.

Prerequisites

You also need the following resources to complete the tutorial hands-on scenario:

Google Workspaces account. Your organization should have it's own Google Workspaces account.
A web browser for accessing the Vault UI.
Vault CLI installed
HashiCorp Cloud Platform account
- HashiCorp Virtual Network (HVN) created in the HCP Portal.
- HCP Vault Dedicated cluster with the public interface enabled; you can deploy the cluster with the steps in Deploy HCP Vault Dedicated with Terraform or Create a Vault Cluster on HCP.

Policy requirements

For this tutorial, the user only has read access to Vault. In a production environment, you would likely to have multiple groups with varying degrees of access to secrets managed by Vault. Vault policies define the role-based access control to govern the client access.

Prepare environment

The goal of this section is for you to prepare and deploy environment needed in this lab.

Create an HCP Vault Dedicated cluster with public cluster accessibility if you don't have one.

Set up Vault CLI

Get token and address from HCP Vault Dedicated instance. See the HCP Vault Dedicated cluster configuration section of Codify management of HCP Vault Dedicated to find the Public Cluster URL and generate a Vault Token and replace the <PUBLIC_CLUSTER_URL> and <YOUR_VAULT_TOKEN> below.

Set up environmental variables:

$ export VAULT_NAMESPACE=admin && export VAULT_ADDR=<PUBLIC_CLUSTER_URL> && export VAULT_TOKEN=<YOUR_VAULT_TOKEN>

Configure Google Workspace

Log into your Google account at Google Service login.
Go to APIs and Services and choose the Credentials link on the left navigation panel.
Choose CREATE PROJECT.
Leave the Project name with the one generated for you, leave the Location as No Organization and choose CREATE.
A Notification should pop up. Next to your project click on Select Project.
Before you can continue you must click on the link for OAuth consent screen on the left nav.
Choose the user type of External and choose Create.
Now the App Information Page appears. For the Application Name choose Vault Client.
The User Support Email can be your Gmail address.
Leave the App Logo blank.
The App domain section can be left blank.
Use the same Gmail address for the Developer Contact Information as you did for the User support email.
Choose Save and Continue.
On the Scopes page leave everything blank and choose Save and Continue.
Leave the Test users black and choose Save and Continue.
Review the Summary and choose Credentials on the left navigation panel.
After the page refreshes, click +Create credentials near the top of the page.
Choose OAuth Client ID.
In the Application Type drop down select Web application, name it my-vault-auth.
On Authorized redirect URIs, click on + ADD URI and then enter $VAULT_ADDR/ui/vault/auth/oidc/oidc/callback substituting the $VAULT_ADDR with your Vault Dedicated's public address.
Press CREATE.
Open a terminal. Now copy the values for Your Client ID and Your Client Secret and make them environmental variables for use later. Update the following command as appropriate.
```
$ export OAUTH_CLIENT_ID=<YOUR_CLIENT_ID> && export OAUTH_CLIENT_SECRET=<YOUR_CLIENT_SECRET>
```

Configure Vault

In the next step, you will use the Client ID and the Client Secret when configuring Vault.

Open a terminal and enable OIDC auth:

$ vault auth enable oidc
Success! Enabled oidc auth method at: oidc/

Configure it with the Google client information

$ vault write auth/oidc/config \
  oidc_discovery_url="https://accounts.google.com" \
  oidc_client_id="$OAUTH_CLIENT_ID" \
  oidc_client_secret="$OAUTH_CLIENT_SECRET" \
  default_role="gmail"

Output should resemble the following:

Success! Data written to: auth/oidc/config

Create a file with text for a read only policy.

$ tee reader.hcl <<EOF
# Read permission on the k/v secrets
path "/secret/*" {
    capabilities = ["read", "list"]
}
EOF

Create the policy.
```
$ vault policy write reader reader.hcl
```
Create a role to use for authentication. You can be as restrictive as desired by using the different "bound" fields. These allow you to specify values that need to be present from Google to allow authentication. Here documentation on claims and values sent by Google, here information on the bound fields.
```
$ vault write auth/oidc/role/gmail \
  user_claim="sub" \
  bound_audiences=$OAUTH_CLIENT_ID \
  allowed_redirect_uris="$VAULT_ADDR/ui/vault/auth/oidc/oidc/callback" \
  policies=reader \
  ttl=1h
```

From the HCP portal, select your Vault cluster. This will load the Overview page.
Under Quick action section find the Web access UI
Click on the Public link. This launches the Vault UI.
In the Method drop down, select OIDC
Enter the role you want to log in to Vault with. This example only have gmail.
The button on the bottom should change and click on the Sign in with Google.
A new window should open, and choose the profile you want to use.
You are now logged into Vault UI.

Clean up

If you are using a Development tier instance of Vault Dedicated, go into HCP and delete your instance.
Change into your home directory
```
cd $HOME
```

Unset the environment variables

$ unset \
MY_VAULT_LICENSE \
VAULT_ADDR \
VAULT_TOKEN

Back in Google Cloud on the Credentials page delete your OAuth 2.0 Client IDs named my-vault-auth by selecting it and clicking on the trash icon.
When prompted confirm you want to delete the credentials.
In order to delete the project, write manage resources in the search bar and and click on the same as it comes up.
A list of resources appears, choose your project and click on the check box and then choose the DELETE link above.
When the Shut down project... dialog appears, follow the directions and choose SHUTDOWN ANYWAY to delete the project.
A window appears confirming the project is shutdown and provides a date for deletion.
Choose OK and close your Google Cloud Window.

Summary

You have learned to set up Single-Sign-On through Google Workspaces in order to securely connect to an Vault Dedicated instance.

This allows you to use a Google Workspace to control login to a Vault instance.

Next steps

This tutorial demonstrates how to setup OIDC auth method using Google Workspace. The tutorial scenario allows anyone with a Google account read only access to your Vault instance. Access to your Vault instance should be restricted according to your organizations policies, and for various groups you want roles with different capabilities. For example, you might want engineers only to be able to read and create secrets in specific namespaces but administrators to have much broader access.

Vault offers two options for managing the users; internal groups and external groups. The Identity: Entities and Groups tutorial demonstrates how to use Vault identity groups.

Each group requires different capabilities, and for more information on how to properly set up policies see Vault Policies.

Help and resources

Build your own plugins

Google Cloud Platform (GCP) auth method