add GCP APIs that need to be enabled to GCP auth docs, small doc fixes (#3446)

This commit is contained in:
emily 2017-10-11 06:18:32 -07:00 committed by Jeff Mitchell
parent 6bafb02a5b
commit cbe41b590f
2 changed files with 15 additions and 17 deletions

View File

@ -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.

View File

@ -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.