open-vault/website/content/docs/auth/gcp.mdx

---
layout: docs
page_title: Google Cloud - Auth Methods
description: |-
  The "gcp" auth method allows users and machines to authenticate to Vault using
  Google Cloud service accounts.
---

# Google Cloud Auth Method

The `gcp` auth method allows Google Cloud Platform entities to authenticate to
Vault. Vault treats Google Cloud as a trusted third party and verifies
authenticating entities against the Google Cloud APIs. This backend allows for
authentication of:

- Google Cloud IAM service accounts
- Google Compute Engine (GCE) instances

This backend focuses on identities specific to Google _Cloud_ and does not
support authenticating arbitrary Google or G Suite users or generic OAuth
against Google.

This plugin is developed in a separate GitHub repository at
[hashicorp/vault-plugin-auth-gcp][repo],
but is automatically bundled in Vault releases. Please file all feature
requests, bugs, and pull requests specific to the GCP plugin under that
repository.

## Authenticate

### Via the CLI Helper

Vault includes a CLI helper that obtains a signed JWT locally and sends the
request to Vault. This helper is only available for IAM-type roles.

```shell-session
$ vault login -method=gcp \
    role="my-role" \
    service_account="authenticating-account@my-project.iam.gserviceaccount.com" \
    jwt_exp="15m" \
    credentials=@path/to/signer/credentials.json
```

For more usage information, run `vault auth help gcp`.

-> **Note:** The `project` parameter has been removed in Vault 1.5.9+, 1.6.5+, and 1.7.2+.
It is no longer needed for configuration and will be ignored if provided.

### Via the CLI

```shell-session
$ vault write -field=token auth/gcp/login \
    role="my-role" \
    jwt="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

See [Generating JWTs](#generating-jwts) for ways to obtain the JWT token.

### Via the API

```shell-session
$ curl \
    --request POST \
    --data '{"role":"my-role", "jwt":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}' \
    http://127.0.0.1:8200/v1/auth/gcp/login
```

See [API docs][api-docs] for expected response.

## Configuration

Auth methods must be configured in advance before users or machines can
authenticate. These steps are usually completed by an operator or configuration
management tool.

1. Enable the Google Cloud auth method:

   ```text
   $ vault auth enable gcp
   ```

1. Configure the auth method credentials:

   ```text
   $ vault write auth/gcp/config \
       credentials=@/path/to/credentials.json
   ```

   If you are using instance credentials or want to specify credentials via
   an environment variable, you can skip this step. To learn more, see the
   [Google Cloud Authentication](#authentication) section below.

1. Create a named role:

   For an `iam`-type role:

   ```text
   $ vault write auth/gcp/role/my-iam-role \
       type="iam" \
       policies="dev,prod" \
       bound_service_accounts="my-service@my-project.iam.gserviceaccount.com"
   ```

   For a `gce`-type role:

   ```text
   $ vault write auth/gcp/role/my-gce-role \
       type="gce" \
       policies="dev,prod" \
       bound_projects="my-project1,my-project2" \
       bound_zones="us-east1-b" \
       bound_labels="foo:bar,zip:zap" \
       bound_service_accounts="my-service@my-project.iam.gserviceaccount.com"
   ```

   Note that `bound_service_accounts` is only required for `iam`-type roles.

   For the complete list of configuration options for each type, please see the
   [API documentation][api-docs].

## Authentication

The Google Cloud Vault auth method uses the official Google Cloud Golang SDK.
This means it supports the common ways of [providing credentials to Google
Cloud][cloud-creds].

1. The environment variable `GOOGLE_APPLICATION_CREDENTIALS`. This is specified
   as the **path** to a Google Cloud credentials file, typically for a service
   account. If this environment variable is present, the resulting credentials are
   used. If the credentials are invalid, an error is returned.

1. Default instance credentials. When no environment variable is present, the
   default service account credentials are used.

For more information on service accounts, please see the [Google Cloud Service
Accounts documentation][service-accounts].

To use this auth method, the service account must have the following minimum
scope:

```text
https://www.googleapis.com/auth/cloud-platform
```

### Required GCP Permissions

#### Vault Server Permissions

**For `iam`-type Vault roles**, Vault can be given the following roles:

```text
roles/iam.serviceAccountKeyAdmin
```

**For `gce`-type Vault roles**, Vault can be given the following roles:

```text
roles/compute.viewer
```

If you instead wish to create a custom role with only the exact GCP permissions
required, use the following list of permissions:

```text
iam.serviceAccounts.get
iam.serviceAccountKeys.get
compute.instances.get
compute.instanceGroups.list
```

These allow Vault to:

- verify the service account, either directly authenticating or associated with
  authenticating GCE instance, exists
- get the corresponding public keys for verifying JWTs signed by service account
  private keys.
- verify authenticating GCE instances exist
- compare bound fields for GCE roles (zone/region, labels, or membership
  in given instance groups)

If you are using Group Aliases as described below, you will also need to add the
`resourcemanager.projects.get` permission.

#### Permissions For Authenticating Against Vault

Note that the previously mentioned permissions are given to the _Vault servers_.
The IAM service account or GCE instance that is **authenticating against Vault**
must have the following role:

```text
roles/iam.serviceAccountTokenCreator
```

!> **WARNING:** Make sure this role is only applied so your service account can
impersonate itself. If this role is applied GCP project-wide, this will allow the service
account to impersonate any service account in the GCP project where it resides.
See [Managing service account impersonation](https://cloud.google.com/iam/docs/impersonating-service-accounts)
for more information.

## Group Aliases

As of Vault 1.0, roles can specify an `add_group_aliases` boolean parameter
that adds [group aliases][identity-group-aliases] to the auth response. These
aliases can aid in building reusable policies since they are available as
interpolated values in Vault's policy engine. Once enabled, the auth response
will include the following aliases:

```json
[
  "project-$PROJECT_ID",
  "folder-$SUBFOLDER_ID",
  "folder-$FOLDER_ID",
  "organization-$ORG_ID"
]
```

If you are using a custom role for Vault server, you will need to add the
`resourcemanager.projects.get` permission to your custom role.

## Implementation Details

This section describes the implementation details for how Vault communicates
with Google Cloud to authenticate and authorize JWT tokens. This information is
provided for those who are curious, but these details are not
required knowledge for using the auth method.

### IAM Login

IAM login applies only to roles of type `iam`. The Vault authentication workflow
for IAM service accounts looks like this:

[![Vault Google Cloud IAM Login Workflow](/img/vault-gcp-iam-auth-workflow.svg)](/img/vault-gcp-iam-auth-workflow.svg)

1. The client generates a signed JWT using the Service Account Credentials
   [`projects.serviceAccounts.signJwt`][signjwt-method] API method. For examples
   of how to do this, see the [Generating JWTs](#generating-jwts) section.

2. The client sends this signed JWT to Vault along with a role name.

3. Vault extracts the `kid` header value, which contains the ID of the
   key-pair used to generate the JWT, and the `sub` ID/email to find the service
   account key. If the service account does not exist or the key is not linked to
   the service account, Vault denies authentication.

4. Vault authorizes the confirmed service account against the given role. If
   that is successful, a Vault token with the proper policies is returned.

### GCE Login

GCE login only applies to roles of type `gce` and **must be completed on an
instance running in GCE**. These steps will not work from your local laptop or
another cloud provider.

[![Vault Google Cloud GCE Login Workflow](/img/vault-gcp-gce-auth-workflow.svg)](/img/vault-gcp-gce-auth-workflow.svg)

1. The client obtains an [instance identity metadata token][instance-identity]
   on a GCE instance.

2. The client sends this JWT to Vault along with a role name.

3. Vault extracts the `kid` header value, which contains the ID of the
   key-pair used to generate the JWT, to find the OAuth2 public cert to verify
   this JWT.

4. Vault authorizes the confirmed instance against the given role, ensuring
   the instance matches the bound zones, regions, or instance groups. If that is
   successful, a Vault token with the proper policies is returned.

## Generating JWTs

This section details the various methods and examples for obtaining JWT
tokens.

### Service Account Credentials API

This describes how to use the GCP Service Account Credentials [API method][signjwt-method]
directly to generate the signed JWT with the claims that Vault expects. Note the CLI
does this process for you and is much easier, and that there is very little
reason to do this yourself.

#### curl Example

Vault requires the following minimum claim set:

```json
{
  "sub": "$SERVICE_ACCOUNT_EMAIL_OR_ID",
  "aud": "vault/$ROLE",
  "exp": "$EXPIRATION"
}
```

For the API method, providing the expiration claim `exp` is required. If it is omitted,
it will not be added automatically and Vault will deny authentication. Expiration must
be specified as a [NumericDate](https://tools.ietf.org/html/rfc7519#section-2) value
(seconds from Epoch). This value must be before the max JWT expiration allowed for a
role. This defaults to 15 minutes and cannot be more than 1 hour.

One you have all this information, the JWT token can be signed using curl and
[oauth2l](https://github.com/google/oauth2l):

```text
ROLE="my-role"
SERVICE_ACCOUNT="service-account@my-project.iam.gserviceaccount.com"
OAUTH_TOKEN="$(oauth2l header cloud-platform)"
EXPIRATION="<your_token_expiration>"
JWT_CLAIM="{\\\"aud\\\":\\\"vault/${ROLE}\\\", \\\"sub\\\": \\\"${SERVICE_ACCOUNT}\\\", \\\"exp\\\": ${EXPIRATION}}"

curl \
  --header "${OAUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --request POST \
  --data "{\"payload\": \"${JWT_CLAIM}\"}" \
  "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/${SERVICE_ACCOUNT}:signJwt"
```

#### gcloud Example

You can also do this through the (currently beta) gcloud command. Note that you will
be required to provide the expiration claim `exp` as a part of the JWT input to the
command.

```shell-session
$ gcloud beta iam service-accounts sign-jwt $INPUT_JWT_CLAIMS $OUTPUT_JWT_FILE \
    --iam-account=service-account@my-project.iam.gserviceaccount.com \
    --project=my-project
```

#### Golang Example

Read more on the
[Google Open Source blog](https://opensource.googleblog.com/2017/08/hashicorp-vault-and-google-cloud-iam.html).

### GCE

GCE tokens **can only be generated from a GCE instance**. The JWT token can be
obtained from the `service-accounts/default/identity` endpoint for a
instance's metadata server.

#### curl Example

```text
ROLE="my-gce-role"

curl \
  --header "Metadata-Flavor: Google" \
  --get \
  --data-urlencode "audience=http://vault/${ROLE}" \
  --data-urlencode "format=full" \
  "http://metadata/computeMetadata/v1/instance/service-accounts/default/identity"
```

## API

The GCP Auth Plugin has a full HTTP API. Please see the
[API docs][api-docs] for more details.

[jwt]: https://tools.ietf.org/html/rfc7519
[signjwt-method]: https://cloud.google.com/iam/docs/reference/credentials/rest/v1/projects.serviceAccounts/signJwt
[cloud-creds]: https://cloud.google.com/docs/authentication/production#providing_credentials_to_your_application
[service-accounts]: https://cloud.google.com/compute/docs/access/service-accounts
[api-docs]: /api/auth/gcp
[identity-group-aliases]: /api/secret/identity/group-alias
[instance-identity]: https://cloud.google.com/compute/docs/instances/verifying-instance-identity
[repo]: https://github.com/hashicorp/vault-plugin-auth-gcp

## Code Example

The following code snippet demonstrates the Google Cloud auth method to authenticate
with Vault.

<CodeTabs heading="gcp auth example">

<CodeBlockConfig lineNumbers>

```go
package main

import (
	"context"
	"encoding/json"
	"fmt"
	"os"
	"time"

	credentials "cloud.google.com/go/iam/credentials/apiv1"
	vault "github.com/hashicorp/vault/api"
	credentialspb "google.golang.org/genproto/googleapis/iam/credentials/v1"
)

// Fetches a key-value secret (kv-v2) after authenticating to Vault via GCP IAM,
// one of two auth methods used to authenticate with GCP (the other is GCE auth).
//
// A role must first be created in Vault bound to the IAM user's service account you wish to authenticate with, like so:
// 	vault write auth/gcp/role/dev-role-iam \
//     	type="iam" \
//     	policies="dev-policy" \
//     	bound_service_accounts="my-service@my-project.iam.gserviceaccount.com"
// Your Vault instance must also be configured with GCP credentials to perform API calls to IAM, like so:
// 	vault write auth/gcp/config credentials=@path/to/server/creds.json
// Learn more at https://www.vaultproject.io/docs/auth/gcp
func getSecretWithGCPAuthIAM() (string, error) {
	config := vault.DefaultConfig() // modify for more granular configuration

	client, err := vault.NewClient(config)
	if err != nil {
		return "", fmt.Errorf("unable to initialize Vault client: %w", err)
	}

	// Learn about authenticating to GCS with service account credentials at https://cloud.google.com/docs/authentication/production
	if pathToCreds := os.Getenv("GOOGLE_APPLICATION_CREDENTIALS"); pathToCreds == "" {
		fmt.Printf("WARNING: Environment variable GOOGLE_APPLICATION_CREDENTIALS was not set. IAM client for JWT signing and Vault server IAM client will both fall back to default instance credentials.\n")
	}

	jwtResp, err := signJWT()
	if err != nil {
		return "", fmt.Errorf("unable to sign JWT for authenticating to GCP: %w", err)
	}

	// send login request to Vault with signed JWT token
	params := map[string]interface{}{
		"role": "dev-role-iam", // the name of the role in Vault that was created with this IAM bound to it
		"jwt":  jwtResp.SignedJwt,
	}

	// Environment variable GOOGLE_APPLICATION_CREDENTIALS pointing to the path to a valid credentials JSON must be set,
	// or Vault will fall back to Google's default instance credentials
	resp, err := client.Logical().Write("auth/gcp/login", params)
	if err != nil {
		return "", fmt.Errorf("unable to log in with GCP IAM auth: %w", err)
	}

	client.SetToken(resp.Auth.ClientToken)

	secret, err := client.Logical().Read("kv-v2/data/creds")
	if err != nil {
		return "", fmt.Errorf("unable to read secret: %w", err)
	}

	data, ok := secret.Data["data"].(map[string]interface{})
	if !ok {
		return "", fmt.Errorf("data type assertion failed: %T %#v", secret.Data["data"], secret.Data["data"])
	}

	// data map can contain more than one key-value pair, in this case we're just grabbing one of them
	key := "password"
	value, ok := data[key].(string)
	if !ok {
		return "", fmt.Errorf("value type assertion failed: %T %#v", data[key], data[key])
	}

	return value, nil
}

// generate signed JWT token from GCP IAM
func signJWT() (*credentialspb.SignJwtResponse, error) {
	svcAccountEmail := fmt.Sprintf("%s@%s.iam.gserviceaccount.com", os.Getenv("GCP_SERVICE_ACCOUNT_NAME"), os.Getenv("GOOGLE_CLOUD_PROJECT"))

	ctx := context.Background()
	iamClient, err := credentials.NewIamCredentialsClient(ctx) // can pass option.WithCredentialsFile("path/to/creds.json") as second param if GOOGLE_APPLICATION_CREDENTIALS env var not set
	if err != nil {
		return nil, fmt.Errorf("unable to initialize IAM credentials client: %w", err)
	}
	defer iamClient.Close()

	resourceName := fmt.Sprintf("projects/-/serviceAccounts/%s", svcAccountEmail)
	jwtPayload := map[string]interface{}{
		"aud": "vault/dev-role-iam", // the name of the role in Vault that was created with this IAM service account bound to it
		"sub": svcAccountEmail,
		"exp": time.Now().Add(time.Minute * 10).Unix(),
	}

	payloadBytes, err := json.Marshal(jwtPayload)
	if err != nil {
		return nil, fmt.Errorf("unable to marshal jwt payload to json: %w", err)
	}

	signJWTReq := &credentialspb.SignJwtRequest{
		Name:    resourceName,
		Payload: string(payloadBytes),
	}

	jwtResp, err := iamClient.SignJwt(ctx, signJWTReq)
	if err != nil {
		return nil, fmt.Errorf("unable to sign JWT: %w", err)
	}

	return jwtResp, nil
}
```

</CodeBlockConfig>

</CodeTabs>