open-vault/website/source/docs/auth/gcp.html.md

325 lines
10 KiB
Markdown
Raw Normal View History

---
layout: "docs"
page_title: "Google Cloud - Auth Methods"
New Docs Website (#5535) * conversion stage 1 * correct image paths * add sidebar title to frontmatter * docs/concepts and docs/internals * configuration docs and multi-level nav corrections * commands docs, index file corrections, small item nav correction * secrets converted * auth * add enterprise and agent docs * add extra dividers * secret section, wip * correct sidebar nav title in front matter for apu section, start working on api items * auth and backend, a couple directory structure fixes * remove old docs * intro side nav converted * reset sidebar styles, add hashi-global-styles * basic styling for nav sidebar * folder collapse functionality * patch up border length on last list item * wip restructure for content component * taking middleman hacking to the extreme, but its working * small css fix * add new mega nav * fix a small mistake from the rebase * fix a content resolution issue with middleman * title a couple missing docs pages * update deps, remove temporary markup * community page * footer to layout, community page css adjustments * wip downloads page * deps updated, downloads page ready * fix community page * homepage progress * add components, adjust spacing * docs and api landing pages * a bunch of fixes, add docs and api landing pages * update deps, add deploy scripts * add readme note * update deploy command * overview page, index title * Update doc fields Note this still requires the link fields to be populated -- this is solely related to copy on the description fields * Update api_basic_categories.yml Updated API category descriptions. Like the document descriptions you'll still need to update the link headers to the proper target pages. * Add bottom hero, adjust CSS, responsive friendly * Add mega nav title * homepage adjustments, asset boosts * small fixes * docs page styling fixes * meganav title * some category link corrections * Update API categories page updated to reflect the second level headings for api categories * Update docs_detailed_categories.yml Updated to represent the existing docs structure * Update docs_detailed_categories.yml * docs page data fix, extra operator page remove * api data fix * fix makefile * update deps, add product subnav to docs and api landing pages * Rearrange non-hands-on guides to _docs_ Since there is no place for these on learn.hashicorp, we'll put them under _docs_. * WIP Redirects for guides to docs * content and component updates * font weight hotfix, redirects * fix guides and intro sidenavs * fix some redirects * small style tweaks * Redirects to learn and internally to docs * Remove redirect to `/vault` * Remove `.html` from destination on redirects * fix incorrect index redirect * final touchups * address feedback from michell for makefile and product downloads
2018-10-19 15:40:11 +00:00
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 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.
```text
$ vault login -method=gcp \
role="my-role" \
service_account="authenticating-account@my-project.iam.gserviceaccount.com" \
project="my-project" \
jwt_exp="15m" \
credentials=@path/to/signer/credentials.json
```
For more usage information, run `vault auth help gcp`.
### Via the CLI
```text
$ 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
```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].
## 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 Permissions
The credentials given to Vault must have the following roles:
```text
roles/iam.serviceAccountKeyAdmin
roles/browser
```
Note that this is the permission **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
```
## 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"
]
```
## 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:
New Docs Website (#5535) * conversion stage 1 * correct image paths * add sidebar title to frontmatter * docs/concepts and docs/internals * configuration docs and multi-level nav corrections * commands docs, index file corrections, small item nav correction * secrets converted * auth * add enterprise and agent docs * add extra dividers * secret section, wip * correct sidebar nav title in front matter for apu section, start working on api items * auth and backend, a couple directory structure fixes * remove old docs * intro side nav converted * reset sidebar styles, add hashi-global-styles * basic styling for nav sidebar * folder collapse functionality * patch up border length on last list item * wip restructure for content component * taking middleman hacking to the extreme, but its working * small css fix * add new mega nav * fix a small mistake from the rebase * fix a content resolution issue with middleman * title a couple missing docs pages * update deps, remove temporary markup * community page * footer to layout, community page css adjustments * wip downloads page * deps updated, downloads page ready * fix community page * homepage progress * add components, adjust spacing * docs and api landing pages * a bunch of fixes, add docs and api landing pages * update deps, add deploy scripts * add readme note * update deploy command * overview page, index title * Update doc fields Note this still requires the link fields to be populated -- this is solely related to copy on the description fields * Update api_basic_categories.yml Updated API category descriptions. Like the document descriptions you'll still need to update the link headers to the proper target pages. * Add bottom hero, adjust CSS, responsive friendly * Add mega nav title * homepage adjustments, asset boosts * small fixes * docs page styling fixes * meganav title * some category link corrections * Update API categories page updated to reflect the second level headings for api categories * Update docs_detailed_categories.yml Updated to represent the existing docs structure * Update docs_detailed_categories.yml * docs page data fix, extra operator page remove * api data fix * fix makefile * update deps, add product subnav to docs and api landing pages * Rearrange non-hands-on guides to _docs_ Since there is no place for these on learn.hashicorp, we'll put them under _docs_. * WIP Redirects for guides to docs * content and component updates * font weight hotfix, redirects * fix guides and intro sidenavs * fix some redirects * small style tweaks * Redirects to learn and internally to docs * Remove redirect to `/vault` * Remove `.html` from destination on redirects * fix incorrect index redirect * final touchups * address feedback from michell for makefile and product downloads
2018-10-19 15:40:11 +00:00
[![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.
New Docs Website (#5535) * conversion stage 1 * correct image paths * add sidebar title to frontmatter * docs/concepts and docs/internals * configuration docs and multi-level nav corrections * commands docs, index file corrections, small item nav correction * secrets converted * auth * add enterprise and agent docs * add extra dividers * secret section, wip * correct sidebar nav title in front matter for apu section, start working on api items * auth and backend, a couple directory structure fixes * remove old docs * intro side nav converted * reset sidebar styles, add hashi-global-styles * basic styling for nav sidebar * folder collapse functionality * patch up border length on last list item * wip restructure for content component * taking middleman hacking to the extreme, but its working * small css fix * add new mega nav * fix a small mistake from the rebase * fix a content resolution issue with middleman * title a couple missing docs pages * update deps, remove temporary markup * community page * footer to layout, community page css adjustments * wip downloads page * deps updated, downloads page ready * fix community page * homepage progress * add components, adjust spacing * docs and api landing pages * a bunch of fixes, add docs and api landing pages * update deps, add deploy scripts * add readme note * update deploy command * overview page, index title * Update doc fields Note this still requires the link fields to be populated -- this is solely related to copy on the description fields * Update api_basic_categories.yml Updated API category descriptions. Like the document descriptions you'll still need to update the link headers to the proper target pages. * Add bottom hero, adjust CSS, responsive friendly * Add mega nav title * homepage adjustments, asset boosts * small fixes * docs page styling fixes * meganav title * some category link corrections * Update API categories page updated to reflect the second level headings for api categories * Update docs_detailed_categories.yml Updated to represent the existing docs structure * Update docs_detailed_categories.yml * docs page data fix, extra operator page remove * api data fix * fix makefile * update deps, add product subnav to docs and api landing pages * Rearrange non-hands-on guides to _docs_ Since there is no place for these on learn.hashicorp, we'll put them under _docs_. * WIP Redirects for guides to docs * content and component updates * font weight hotfix, redirects * fix guides and intro sidenavs * fix some redirects * small style tweaks * Redirects to learn and internally to docs * Remove redirect to `/vault` * Remove `.html` from destination on redirects * fix incorrect index redirect * final touchups * address feedback from michell for makefile and product downloads
2018-10-19 15:40:11 +00:00
[![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.
### IAM
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 Example
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)"
JWT_CLAIM="{\\\"aud\\\":\\\"vault/${ROLE}\\\", \\\"sub\\\": \\\"${SERVICE_ACCOUNT}\\\"}"
curl \
--header "${OAUTH_TOKEN}" \
--header "Content-Type: application/json" \
--request POST \
--data "{\"payload\": \"${JWT_CLAIM}\"}" \
"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 \
2018-10-21 00:35:33 +00:00
--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/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
[repo]: https://github.com/hashicorp/vault-plugin-auth-gcp