HashiDays One conference. Three cities. Find a city near you
Vault
Vault Home

You are viewing documentation for version v1.14.x. View latest version.

Google

Main reference: Using OAuth 2.0 to Access Google APIs

  1. Visit the Google API Console.
  2. Create or a select a project.
  3. Navigate to Menu > APIs & Services
  4. Create a new credential via Credentials > Create Credentials > OAuth Client ID.
  5. Configure the OAuth Consent Screen. Application Name is required. Save.
  6. Select application type: "Web Application".
  7. Configure Authorized Redirect URIs.
  8. Save client ID and secret.

Optional google-specific configuration

Google-specific configuration is available when using Google as an identity provider from the Vault JWT/OIDC auth method. The configuration allows Vault to obtain Google Workspace group membership and user information during the JWT/OIDC authentication flow. The group membership obtained from Google Workspace may be used for Identity group alias association. The user information obtained from Google Workspace can be used to copy claims data into resulting auth token and alias metadata via claim_mappings.

Setup

To set up the Google-specific handling, you'll need:

  • A Google Workspace account with the super admin role for granting domain-wide delegation API client access.
  • The ability to create a service account in Google Cloud Platform.
  • To enable the Admin SDK API.
  • An OAuth 2.0 application with an internal user type. We do not recommend using an external user type since it would allow any user with a Google account to authenticate with Vault.

The Google-specific handling that's used to fetch Google Workspace groups and user information in Vault uses Google Workspace Domain-Wide Delegation of Authority for authentication and authorization. You need to follow all steps in the guide to obtain the key file for a Google service account capable of making requests to the Google Workspace User Accounts and Groups APIs.

In step 11 within the section titled Optional: Set up domain-wide delegation for a service account, the only OAuth scopes that should be granted are:

This is an important security step in order to give the service account the least set of privileges that enable the feature.

Configuration

  • provider (string: <required>) - Name of the provider. Must be set to "gsuite".
  • gsuite_service_account (string: <required>) - Either the path to or the contents of a Google service account key file in JSON format. If given as a file path, it must refer to a file that's readable on the host that Vault is running on. If given directly as JSON contents, the JSON must be properly escaped.
  • gsuite_admin_impersonate (string: <required>) - Email address of a Google Workspace admin to impersonate.
  • fetch_groups (bool: false) - If set to true, groups will be fetched from Google Workspace.
  • fetch_user_info (bool: false) - If set to true, user info will be fetched from Google Workspace using the configured user_custom_schemas.
  • groups_recurse_max_depth (int: <optional>) - Group membership recursion max depth. Defaults to 0, which means don't recurse.
  • user_custom_schemas (string: <optional>) - Comma-separated list of Google Workspace custom schemas. Values set for Google Workspace users using custom schema fields will be fetched and made available as claims that can be used with claim_mappings. Required if fetch_user_info is set to true.

Example configuration:

vault write auth/oidc/config -<<EOF{    "oidc_discovery_url": "https://accounts.google.com",    "oidc_client_id": "your_client_id",    "oidc_client_secret": "your_client_secret",    "default_role": "your_default_role",    "provider_config": {        "provider": "gsuite",        "gsuite_service_account": "/path/to/service-account.json",        "gsuite_admin_impersonate": "admin@gsuitedomain.com",        "fetch_groups": true,        "fetch_user_info": true,        "groups_recurse_max_depth": 5,        "user_custom_schemas": "Education,Preferences"    }}EOF

Role

The user_claim value of the role must be set to one of either sub or email for the Google Workspace group and user information queries to succeed.

Example role:

vault write auth/oidc/role/your_default_role \    allowed_redirect_uris="http://localhost:8200/ui/vault/auth/oidc/oidc/callback,http://localhost:8250/oidc/callback" \    user_claim="sub" \    groups_claim="groups" \    claim_mappings="/Education/graduation_date"="graduation_date" \    claim_mappings="/Preferences/shirt_size"="shirt_size"