From ea412e52b722a4df7ae4b4c1cf1a2ae471d6a4aa Mon Sep 17 00:00:00 2001 From: emily Date: Wed, 11 Oct 2017 06:18:32 -0700 Subject: [PATCH] add GCP APIs that need to be enabled to GCP auth docs, small doc fixes (#3446) --- website/source/api/auth/gcp/index.html.md | 13 +------------ website/source/docs/auth/gcp.html.md | 19 ++++++++++++++----- 2 files changed, 15 insertions(+), 17 deletions(-) diff --git a/website/source/api/auth/gcp/index.html.md b/website/source/api/auth/gcp/index.html.md index cfedc24e9f..cbe28fb6df 100644 --- a/website/source/api/auth/gcp/index.html.md +++ b/website/source/api/auth/gcp/index.html.md @@ -148,35 +148,24 @@ entities attempting to login. inferred from service account used to issue metadata token for GCE instances. **`iam`-only params**: - - `max_jwt_exp` `(string: "")` - Optional, defaults to 900 (15min). Number of seconds past the time of authentication that the login param JWT must expire within. For example, if a user attempts to login with a token that expires within an hour and this is set to 15 minutes, Vault will return an error prompting the user to create a new signed JWT with a shorter `exp`. The GCE metadata tokens currently do not allow the `exp` claim to be customized. - - `allow_gce_inference` `(bool: true)` - A flag to determine if this role should allow GCE instances to authenticate by inferring service accounts from the GCE identity metadata token. - -- `service_accounts` `(array: [])` - Required for `iam` roles. - A comma-separated list of service account emails or ids. - Defines the service accounts that login is restricted to. If set to `*`, all - service accounts are allowed (role will still be bound by project). - + **`gce`-only params**: - - `bound_zone` `(string: "")`: If set, determines the zone that a GCE instance must belong to. If bound_instance_group is provided, it is assumed to be a zonal group and the group must belong to this zone. - - `bound_region` `(string: "")`: If set, determines the region that a GCE instance must belong to. If bound_instance_group is provided, it is assumed to be a regional group and the group must belong to this region. **If bound_zone is provided, region will be ignored.** - - `bound_instance_group` `(string: "")`: If set, determines the instance group that an authorized instance must belong to. bound_zone or bound_region must also be set if bound_instance_group is set. - - `bound_labels` `(array: [])`: A comma-separated list of Google Cloud Platform labels formatted as "$key:$value" strings that must be set on authorized GCE instances. Because GCP labels are not currently ACL'd, we recommend that this be used in conjunction with other restrictions. diff --git a/website/source/docs/auth/gcp.html.md b/website/source/docs/auth/gcp.html.md index 030ecb6398..772167042e 100644 --- a/website/source/docs/auth/gcp.html.md +++ b/website/source/docs/auth/gcp.html.md @@ -19,14 +19,23 @@ Currently supports authentication for: * GCP IAM service accounts (`iam`) * GCE IAM service accounts (`gce`) -We will update the documentation as we introduce more supported entities. +## Precursors: The following documentation assumes that the backend has been [mounted](/docs/plugin/index.html) at `auth/gcp`. -~> Note: The `gcp` backend is implemented as a -[Vault plugin](/docs/internals/plugins.html) backend. You must be using Vault -v0.8.0+ to use plugins. +You must also [enable the following GCP APIs](https://support.google.com/cloud/answer/6158841?hl=en) +for your GCP project: + + * IAM API for both `iam` service accounts and `gce` instances + * GCE API for just `gce` instances + +The next sections review how the authN/Z workflows work. If you +have already reviewed these sections, here are some quick links to: + + * [Usage](#usage) + * [API documentation](/api/auth/gcp/index.html) docs. + ## Authentication Workflow @@ -34,7 +43,7 @@ v0.8.0+ to use plugins. The Vault authentication workflow for IAM service accounts is as follows: - 1. A client with IAM service account credentials generates a signed JWT using the IAM [projects.serviceAccounts.signJwt](https://cloud.google.com/iam/reference/rest/v1/projects.serviceAccounts/signJwt) method. See [usage](#the-iam-authentication-token) for the expected format and example code. + 1. A client with IAM service account credentials generates a signed JWT using the IAM [projects.serviceAccounts.signJwt](https://cloud.google.com/iam/reference/rest/v1/projects.serviceAccounts/signJwt) method. See [here](#the-iam-authentication-token) for the expected format and example code. 2. The client sends this JWT to Vault in a login request with a role name. This role should have type `iam`. 3. Vault grabs 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 will deny authentication. 4. Vault authorizes the confirmed service account against the given role. See [authorization section](#authorization-workflow) to see how each type of role handles authorization.