---
layout: "docs"
page_title: "Google Cloud - Auth Methods"
sidebar_title: "Google Cloud"
sidebar_current: "docs-auth-gcp"
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 (GCP) entities to
authenticate to Vault. Vault treats GCP as a Trusted Third Party and
verifies authenticating entities against GCP APIs. This backend allows
for authentication of:

* IAM service accounts
* Google Compute Engine (GCE) instances

**NOTE**: This backend focuses on identities specific to Google Cloud and
does not support authenticating Google users (i.e. `type: "authorized_user"`) 
or OAuth against Google

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

## Quick Start

To authenticate, you will need two things:

1. Proof-of-identity: 
    * Service Account: A signed [JSON Web Token][jwt] (JWT), or GCP credentials 
    with permissions to sign a JWT (see [`signJwt`][signjwt-method] IAM API 
    method) for this service account
    * Access to a metadata server for a GCE instance
1. Name of a `role`, a binding of Vault policies and authZ 
   restrictions preconfigured for the GCP auth backend that
   an entity authenticates under. Roles are either type `iam`, which
   supports either type of entity, or `gce`, which support only GCE instances.

### Via CLI

The default path is `/gcp`. If this auth method was enabled at a different
path, specify `-path=/my-path` in the CLI. 
The backend takes a signed [JSON Web Token][jwt] (JWT) as proof-of-identity.

#### Generate `iam` JWT and Login
 
Because the process to sign a service account JWT can be tedious, Vault includes
a CLI helper that handles obtaining a properly-formatted and signed JWT on your
client before sending an actual request to the Vault server. This process 
**only applies to `iam`-type roles!** For GCE instances, the JWT is 
automatically generated by Google and exposed as metadata.

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

Note that `credentials` must have signJwt permissions on `service_account`. 

*Optional Fields*: 
* `credentials` can be omitted to default to Application Default Credentials.
* `service_account` or `project` can be omitted and Vault will attempt
   to default to values in `credentials`. However, Vault will return an 
   error if the `credentials` are not a valid service account key file.

For more details on each field, please run `vault auth help gcp`.

#### Login With Existing JWT

If you already have an existing service account JWT that you generated
from the API or by yourself, you can run the following command to 
login. 


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

#### Obtaining `gce` JWT (Metadata)

GCE tokens are obtained from a GCE instance's own metadata server endpoint, 
`service-accounts/default/identity`. 

**You must run these example commands from the GCE instance.**. 

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

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

Since instances currently only support one service account, you can use 
`default` as we do to refer to the associated service account. You can also 
use the actual service account email or ID.
  
### Via the API

```text
$ 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](#google-cloud-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"
    ```

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


### Google Cloud 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 storage backend, the service account must have the following
minimum scope(s):

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

### Vault Identity Features

This section describes features related to Vault's 
[Identity](/docs/secrets/identity/index.html)
system. Since the Identity system was released after the initial GCP auth 
backend plugin was released, this will generally cover features
we have added in newer releases of the plugin.

#### Group Aliases

Roles now have a `add_group_aliases` boolean parameter that adds 
[Group Aliases][identity-group-aliases] to the auth response. For example,
for a project `$PROJECT_ID`, in subfolder `$SUBFOLDER_ID`,
in folder `$FOLDER_ID`, in organization `$ORG_ID`, the following group aliases
will be added:

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

Note this is opt-in as it requires a project-level or organizational-level
Google IAM permission `resourcemanager.projects.get`. 

## Appendixes 

### Implementation Details and Workflow

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 IAM
  [`projects.serviceAccounts.signJwt`][signjwt-method] method. For examples of
  how to do this, see the [Obtaining JWT Tokens](#obtaining-jwt-tokens) 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 IAM JWT

This describes how to use the GCP IAM [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

Vault requires the following minimum claim set:

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

For the API method, expiration is optional and will default to an hour. 
If specified, expiration must be 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"
PROJECT="my-project"
SERVICE_ACCOUNT="service-account@my-project.iam.gserviceaccount.com"
OAUTH_TOKEN="$(oauth2l header cloud-platform)"

curl \
  --header "${OAUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --request POST \
  --data "{\"aud\":\"vault/${ROLE}\", \"sub\": \"${SERVICE_ACCOUNT}\"}" \
  "https://iam.googleapis.com/v1/projects/${PROJECT}/serviceAccounts/${SERVICE_ACCOUNT}:signJwt"
```

#### gcloud Example

You can also do this through the (currently beta) gcloud command. 

```text
$ 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).

### Generating GCE Tokens

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

```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/reference/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/index.html
[identity-group-aliases]: /api/secret/identity/group-alias.html
[instance-identity]: https://cloud.google.com/compute/docs/instances/verifying-instance-identity