luxolus
/
open-vault
2
0
Fork 0
Code Issues 1 Pull Requests Releases Activity

Update GCP docs (#4898) 

* Consistently use "Google Cloud" where appropriate

* Update GCP docs

This updates the GCP docs to use the new updated fields that will be
present in the next release of the plugin as well as fixes up some
inconsistencies between the GCP docs and other auth method
documentation.
This commit is contained in:
Seth Vargo 2018-07-11 15:52:22 -04:00 committed by Jeff Mitchell
parent a0c09278ee
commit a379989da4
8 changed files with 545 additions and 972 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
website/data/news.yml
View File

@ -5,7 +5,8 @@ posts:
body: >-
We are proud to announce the release of HashiCorp Vault 0.10. This
version includes an open source web UI, versioned key-value secrets,
Azure authentication, GCP Secrets Engine, Root DB credential rotation, and much more!
Azure authentication, Google Cloud Secrets Engine, Root DB credential
rotation, and much more!
link_url: "https://www.hashicorp.com/blog/vault-0-10/"
-
title: "Vault 0.9 released"

390
website/source/api/auth/gcp/index.html.md
View File

@ -1,17 +1,17 @@
---
layout: "api"
page_title: "Google Cloud Platform - Auth Methods - HTTP API"
page_title: "Google Cloud - Auth Methods - HTTP API"
sidebar_current: "docs-http-auth-gcp"
description: |-
This is the API documentation for the Vault GCP authentication
method plugin.
This is the API documentation for the Vault Google Cloud authentication
method.
---
# GCP Auth Method (API)
# Google Cloud Auth Method (API)
This is the API documentation for the Vault GCP auth method
plugin. To learn more about the usage and operation, see the
[Vault GCP method documentation](/docs/auth/gcp.html).
This is the API documentation for the Vault Google Cloud auth method. To learn
more about the usage and operation, see the
[Vault Google Cloud method documentation](/docs/auth/gcp.html).
This documentation assumes the plugin method is mounted at the
`/auth/gcp` path in Vault. Since it is possible to enable auth methods
@ -20,36 +20,38 @@ at any location, please update your API calls accordingly.
## Configure
Configures the credentials required for the plugin to perform API calls
to GCP. These credentials will be used to query the status of IAM
to Google Cloud. These credentials will be used to query the status of IAM
entities and get service account or other Google public certificates
to confirm signed JWTs passed in during login.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/auth/gcp/config` | `204 (empty body)` |
| `POST` | `/auth/gcp/config` | `204 (empty body)` |
### Parameters
- `credentials` `(string: "")` - A marshaled JSON string that is the content
of a GCP credentials file. If you would rather specify a file, you can use
`credentials="@path/to/creds.json`. The GCP permissions
Vault currently requires are:
- `iam.serviceAccounts.get`
- `iam.serviceAccountKeys.get`
- `credentials` `(string: "")` - A JSON string containing the contents
of a GCP credentials file. The credentials file must have the following
[permissions](https://cloud.google.com/compute/docs/access/iam):
If this value is not specified or if it is explicitly set to empty,
Vault will attempt to use [Application Default Credentials](https://developers.google.com/identity/protocols/application-default-credentials)
for that server's machine.
```
iam.serviceAccounts.get
iam.serviceAccountKeys.get
```
- `google_certs_endpoint` `(string: "")`: The Google OAuth2 endpoint to obtain public certificates for. This is used
primarily for testing and should generally not be set. If not set, will default to the [Google public certs
endpoint](https://www.googleapis.com/oauth2/v3/certs)
If this value is empty, Vault will try to use [Application Default
Credentials][gcp-adc] from the machine on which the Vault server is running.
- `google_certs_endpoint` `(string:
"https://www.googleapis.com/oauth2/v3/certs")`: The Google OAuth2 endpoint
from which to obtain public certificates. This is used for testing and should
generally not be set by end users.
### Sample Payload
```json
{
"credentials": "{ \"type\": \"service_account\", \"project_id\": \"project-123456\",...}"
"credentials": "{ \"type\": \"service_account\", \"project_id\": \"project-123456\", ...}"
}
```
@ -65,7 +67,7 @@ $ curl \
## Read Config
Returns the previously configured config, including credentials.
Returns the configuration, if any, including credentials.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
@ -83,22 +85,18 @@ $ curl \
```json
{
"data":{
"client_email":"serviceaccount1@project-123456.iam.gserviceaccount.com",
"client_id":"...",
"private_key":"-----BEGIN PRIVATE KEY-----...-----END PRIVATE KEY-----\n",
"private_key_id":"...",
"project_id":"project-123456",
"google_certs_url": ""
"data": {
"client_email": "service-account@project-123456.iam.gserviceaccount.com",
"client_id": "123456789101112131415",
"private_key_id": "97fd7ba59a96e1f3830296aedb4f50879e4d5382",
"project_id": "project-123456"
},
...
}
```
## Delete Config
Deletes the previously configured GCP config and credentials.
Deletes all GCP configuration data. This operation is idempotent.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
@ -125,97 +123,107 @@ entities attempting to login.
| `POST` | `/auth/gcp/role/:name` | `204 (empty body)` |
### Parameters
- `name` `(string: <required>)` - Name of the role.
- `type` `(string: <required>)` - The type of this role. Only the
restrictions applicable to this role type will be allowed to
be configured on the role (see below). Valid choices are: `iam`.
- `project_id` `(string: "")` - Required. Only entities belonging to this
project can login for this role.
- `ttl` `(string: "")` - The TTL period of tokens issued using this role in
seconds.
- `max_ttl` `(string: "")` - The maximum allowed lifetime of tokens
issued in seconds using this role.
- `name` `(string: <required>)` - The name of the role.
- `type` `(string: <required>)` - The type of this role. Certain fields
correspond to specific roles and will be rejected otherwise. Please see below
for more information.
- `project_id` `(string: <required>)` - The GCP project ID. Only entities belonging to this
project can authenticate with this role.
- `ttl` `(string: "")` - The TTL period of tokens issued using this role. This
can be specified as an integer number of seconds or as a duration value like
"5m".
- `max_ttl` `(string: "")` - The maximum allowed lifetime of tokens issued in
seconds using this role. This can be specified as an integer number of seconds
or as a duration value like "5m".
- `period` `(string: "")` - If set, indicates that the token generated using
this role should never expire. The token should be renewed within the duration
specified by this value. At each renewal, the token's TTL will be set to the
value of this parameter.
- `policies` `(array: [])` - Policies to be set on tokens issued using this
role.
- `bound_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). Will be
inferred from service account used to issue metadata token for GCE instances.
value of this parameter. This can be specified as an integer number of seconds
or as a duration value like "5m".
**`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.
- `policies` `(array: [default])` - The list of policies to be set on tokens
issued using this role.
- `bound_bound_service_accounts` `(array: <required for iam>)` - A comma-separated
list of service account emails or IDs that login is restricted to. If set to
`*`, all service accounts are allowed (role will still be bound by project).
Will be inferred from service account used to issue metadata token for GCE
instances.
#### `iam`-only Parameters
The following parameters are only valid when the role is of type `"iam"`:
- `max_jwt_exp` `(string: "15m")` - The 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.
**`gce`-only params**:
#### `gce`-only Parameters
- `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.
The following parameters are only valid when the role is of type `"gce"`:
- `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.
- `bound_zones` `(array: [])`: The list of zones that a GCE instance must belong
to in order to be authenticated. If `bound_instance_groups` is provided, it is
assumed to be a zonal group and the group must belong to this zone.
- `bound_regions` `(array: [])`: The list of regions that a GCE instance must
belong to in order to be authenticated. If `bound_instance_groups` is
provided, it is assumed to be a regional group and the group must belong to
this region. If `bound_zones` are provided, this attribute is ignored.
- `bound_instance_groups` `(array: [])`: The instance groups that an authorized
instance must belong to in order to be authenticated. If specified, either
`bound_zones` or `bound_regions` must be set too.
- `bound_labels` `(array: [])`: A comma-separated list of GCP 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.
### Sample Payload
Example `iam` Role:
Example `iam` role:
```json
{
"type": "iam",
"project": "project-123456",
"policies": [
"default",
"dev",
"prod"
],
"max_ttl": 1800000,
"max_jwt_exp": 10000,
"service_accounts": [
"dev-1@project-123456.iam.gserviceaccount.com",
"dev-2@project-123456.iam.gserviceaccount.com",
"123456789"
],
"allow_instance_migration": false
"project_id": "project-123456",
"policies": ["prod"],
"ttl": "30m",
"max_ttl": "24h",
"max_jwt_exp": "5m",
"bound_bound_service_accounts": [
"dev-1@project-123456.iam.gserviceaccount.com"
]
}
```
Example `gce` Role:
Example `gce` role:
```json
{
"type": "gce",
"project": "project-123456",
"policies": [
"default",
"dev",
"prod"
],
"max_ttl": 1800000,
"max_jwt_exp": 10000,
"service_accounts": [
"dev-1@project-123456.iam.gserviceaccount.com",
"dev-2@project-123456.iam.gserviceaccount.com",
"123456789"
],
"allow_instance_migration": false
"project_id": "project-123456",
"policies": ["prod"],
"bound_zones": ["us-east1-b", "eu-west2-a"],
"ttl": "30m",
"max_ttl": "24h",
"bound_service_accounts": [
"dev-1@project-123456.iam.gserviceaccount.com"
]
}
```
@ -226,10 +234,10 @@ $ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/gcp/role/dev-role
http://127.0.0.1:8200/v1/auth/gcp/role/my-role
```
## Edit Service Accounts For IAM Role
## Edit Service Accounts on IAM Role
Edit service accounts for an existing IAM role in the method.
This allows you to add or remove service accounts from the list of
@ -240,23 +248,26 @@ service accounts on the role.
| `POST` | `/auth/gcp/role/:name/service-accounts` | `204 (empty body)` |
### Parameters
- `name` `(string: <required>)` - Name of an existing `iam` role.
Returns error if role is not an `iam` role.
- `add` `(array: [])` - List of service accounts to add to the role's
service accounts
- `remove` `(array: [])` - List of service accounts to remove from the
role's service accounts
- `name` `(string: <required>)` - The name of an existing `iam` type role. This
will return an error if role is not an `iam` type role.
- `add` `(array: [])` - The list of service accounts to add to the role's
service accounts.
- `remove` `(array: [])` - The list of service accounts to remove from the
role's service accounts.
### Sample Payload
```json
{
"add": [
"dev-1@project-123456.iam.gserviceaccount.com",
"123456789"
"dev-1@project-123456.iam.gserviceaccount.com",
"123456789"
],
"remove": [
"dev-2@project-123456.iam.gserviceaccount.com"
"dev-2@project-123456.iam.gserviceaccount.com"
]
}
```
@ -268,35 +279,42 @@ $ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/gcp/role/dev-role
http://127.0.0.1:8200/v1/auth/gcp/role/my-role
```
## Edit Labels For GCE Role
## Edit Labels on GCE Role
Edit service accounts for an existing IAM role in the backend.
This allows you to add or remove service accounts from the list of
service accounts on the role.
Edit labels for an existing GCE role in the backend. This allows you to add or
remove labels (keys, values, or both) from the list of keys on the role.
| Method | Path | Produces |
| :------- | :---------------------------------------| :------------------|
| `POST` | `/auth/gcp/role/:name/labels` | `204 (empty body)` |
| `POST` | `/auth/gcp/role/:name/labels` | `204 (empty body)` |
### Parameters
- `name` `(string: <required>)` - Name of an existing `gce` role. Returns error if role is not an `gce` role.
- `add` `(array: [])` - List of `$key:$value` labels to add to the GCE role's bound labels.
- `remove` `(array: [])` - List of label keys to remove from the role's bound labels.
- `name` `(string: <required>)` - The name of an existing `gce` role. This will
return an error if role is not a `gce` type role.
- `add` `(array: [])` - The list of `key:value` labels to add to the GCE role's
bound labels.
- `remove` `(array: [])` - The list of label _keys_ to remove from the role's
bound labels. If any of the specified keys do not exist, no error is returned
(idempotent).
### Sample Payload
```json
{
"add": [
"foo:bar",
"env:dev",
"key:value"
"foo:bar",
"env:dev",
"key:value"
],
"remove": [
"keyInLabel1, keyInLabel2"
"key1",
"key2"
]
}
```
@ -308,7 +326,7 @@ $ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/gcp/role/dev-role
http://127.0.0.1:8200/v1/auth/gcp/role/my-role
```
## Read Role
@ -317,45 +335,46 @@ Returns the previously registered role configuration.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `GET` | `/auth/gcp/role/:name` | `200 application/json` |
| `GET` | `/auth/gcp/role/:name` | `200 application/json` |
### Parameters
- `name` `(string: <required>)` - Name of the role.
- `name` `(string: <required>)` - The name of the role to read.
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/gcp/role/dev-role
http://127.0.0.1:8200/v1/auth/gcp/role/my-role
```
### Sample Response
```json
{
"data":{
"max_jwt_exp": 900,
"max_ttl": 0,
"ttl":0,
"period": 0,
"policies":[
"default",
"dev",
"prod"
],
"project_id":"project-123456",
"role_type":"iam",
"service_accounts": [
"dev-1@project-123456.iam.gserviceaccount.com",
"dev-2@project-123456.iam.gserviceaccount.com",
"123456789",
]
"data": {
"bound_labels": {
"env": "dev",
"foo": "bar",
"key": "value"
},
...
"bound_service_accounts": [
"dev-1@project-123456.iam.gserviceaccount.com"
],
"bound_zones": [
"eu-west2-a",
"us-east1-b"
],
"max_ttl": 86400,
"policies": [
"prod"
],
"project_id": "project-123456",
"role_type": "gce",
"ttl": 1800
}
}
```
## List Roles
@ -379,13 +398,12 @@ $ curl \
```json
{
"data": {
"keys": [
"dev-role",
"prod-role"
]
},
...
"data": {
"keys": [
"my-role",
"my-other-role"
]
}
}
```
@ -399,7 +417,7 @@ Deletes the previously registered role.
### Parameters
- `role` `(string: <required>)` - Name of the role.
- `role` `(string: <required>)` - The name of the role to delete.
### Sample Request
@ -407,14 +425,15 @@ Deletes the previously registered role.
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/auth/gcp/role/dev-role
http://127.0.0.1:8200/v1/auth/gcp/role/my-role
```
## Login
Fetch a token. This endpoint takes a signed JSON Web Token (JWT) and
a role name for some entity. It verifies the JWT signature to authenticate that
entity and then authorizes the entity for the given role.
Login to retrieve a Vault token. This endpoint takes a signed JSON Web Token
(JWT) and a role name for some entity. It verifies the JWT signature with Google
Cloud to authenticate that entity and then authorizes the entity for the given
role.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
@ -422,20 +441,23 @@ entity and then authorizes the entity for the given role.
### Sample Payload
- `role` `(string: "")` - Name of the role against which the login is being
attempted.
- `jwt` `(string: "")` - Signed [JSON Web Token](https://tools.ietf.org/html/rfc7519) (JWT).
For `iam`, this is a JWT generated using the IAM API method
[signJwt](https://cloud.google.com/iam/reference/rest/v1/projects.serviceAccounts/signJwt)
or a self-signed JWT. For `gce`, this is an [identity metadata token](https://cloud.google.com/compute/docs/instances/verifying-instance-identity#request_signature).
- `role` `(string: <required>)` - The name of the role against which the login
is being attempted.
- `jwt` `(string: <required>)` - A Signed [JSON Web Token][jwt].
- For `iam` type roles, this is a JWT signed with the
[`signJwt` method][signjwt-method] or a self-signed JWT.
- For `gce` type roles, this is an [identity metadata token][instance-token].
### Sample Payload
```json
{
"role": "dev-role",
"jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
"role": "my-role",
"jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```
@ -452,22 +474,26 @@ $ curl \
```json
{
"auth":{
"client_token":"f33f8c72-924e-11f8-cb43-ac59d697597c",
"accessor":"0e9e354a-520f-df04-6867-ee81cae3d42d",
"policies":[
"default",
"dev",
"prod"
],
"metadata":{
"role": "dev-role",
"service_account_email": "dev1@project-123456.iam.gserviceaccount.com",
"service_account_id": "111111111111111111111"
},
"lease_duration":2764800,
"renewable":true
"auth": {
"client_token": "f33f8c72-924e-11f8-cb43-ac59d697597c",
"accessor": "0e9e354a-520f-df04-6867-ee81cae3d42d",
"policies": [
"default",
"dev",
"prod"
],
"metadata": {
"role": "my-role",
"service_account_email": "dev1@project-123456.iam.gserviceaccount.com",
"service_account_id": "111111111111111111111"
},
...
"lease_duration": 2764800,
"renewable": true
}
}
```
[gcp-adc]: https://developers.google.com/identity/protocols/application-default-credentials
[jwt]: https://tools.ietf.org/html/rfc7519
[signjwt-method]: https://cloud.google.com/iam/reference/rest/v1/projects.serviceAccounts/signJwt
[instance-token]: https://cloud.google.com/compute/docs/instances/verifying-instance-identity#request_signature

8
website/source/api/secret/gcp/index.html.md
View File

@ -1,14 +1,14 @@
---
layout: "api"
page_title: "GCP - Secrets Engines - HTTP API"
page_title: "Google Cloud - Secrets Engines - HTTP API"
sidebar_current: "docs-http-secret-gcp"
description: |-
This is the API documentation for the Vault GCP secrets engine.
This is the API documentation for the Vault Google Cloud secrets engine.
---
# GCP Secrets Engine (API)
# Google Cloud Secrets Engine (API)
This is the API documentation for the Vault GCP (Google Cloud Platform)
This is the API documentation for the Vault Google Cloud Platform (GCP)
secrets engine. For general information about the usage and operation of
the GCP secrets engine, please see [these docs](/docs/secrets/gcp/index.html).

4
website/source/api/system/plugins-reload-backend.html.md
View File

@ -23,10 +23,10 @@ This endpoint reloads mounted plugin backends.
### Parameters
- `plugin` `(string: "")` – The name of the plugin to reload, as
- `plugin` `(string: "")` – The name of the plugin to reload, as
registered in the plugin catalog.
- `mounts` `(slice: [])` – Array or comma-separated string mount paths
- `mounts` `(array: [])` – Array or comma-separated string mount paths
of the plugin backends to reload.
### Sample Payload

206
website/source/assets/images/vault-gcp-gce-auth-workflow.svg
View File

File diff suppressed because one or more lines are too long
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 312 KiB

After

Width:  |  Height:  |  Size: 31 KiB

164
website/source/assets/images/vault-gcp-iam-auth-workflow.svg
View File

File diff suppressed because one or more lines are too long
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 415 KiB

After

Width:  |  Height:  |  Size: 30 KiB

740
website/source/docs/auth/gcp.html.md
View File

@ -1,518 +1,298 @@
---
layout: "docs"
page_title: "GCP - Auth Methods"
page_title: "Google Cloud - Auth Methods"
sidebar_current: "docs-auth-gcp"
description: |-
The gcp auth method plugin allows automated authentication of AWS entities.
The "gcp" auth method allows users and machines to authenticate to Vault using
Google Cloud service accounts.
---
# GCP Auth Method
# Google Cloud Auth Method
The `gcp` auth method allows authentication against Vault using
Google credentials. It treats GCP as a Trusted Third Party and expects a
[JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519) signed by Google
credentials from the authenticating entity. This token can be generated through
different GCP APIs depending on the type of entity.
Currently supports authentication for:
* GCP IAM service accounts (`iam`)
* GCE IAM service accounts (`gce`)
## Quick Links
* [API documentation](/api/auth/gcp/index.html)
* [Usage: Setup](#setup): How to set up the auth backend on the server
* [Usage: Authentication](#authentication): How to authenticate to Vault using this backend
* [Workflows](#authentication-workflow): Authentication and authorization workflows in more detail
## Setup
The following documentation assumes that the method has been
[mounted](/docs/plugin/index.html) at `auth/gcp`.
```sh
$ vault auth enable 'gcp'
Success! Enabled gcp auth method at: gcp/
```
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
There are generally two setup steps:
### 1. Config
Example:
```sh
$ vault write auth/gcp/config credentials=@/path/to/creds.json
```
This step allows you to explicitly set GCP credentials that Vault (this auth backend) uses.
If credentials are not configured or if the user explicitly sets the config with no credentials,
the Vault server will attempt to infer credentials. In order of preference, the auth method will use
the first credentials it finds from the following:
* Provided JSON as `credentials` arg
* Environment variables `GOOGLE_CREDENTIALS` or `GOOGLE_CLOUD_KEYFILE_JSON` set to the credentials JSON string
* JSON file `~/.gcp/credentials`
* [Google Application Default Credentials](https://developers.google.com/identity/protocols/application-default-credentials)
For the complete list of configuration options, see the [API documentation](/api/auth/gcp/index.html#configure).
### 2. Roles
Example:
```sh
$ vault write auth/gcp/role/dev-iam-role \
type="iam" \
project_id="project-123456" \
policies="dev" \
bound_service_accounts="serviceaccount1@project1234.iam.gserviceaccount.com,uuid123,..."
$ vault write auth/gcp/role/prod-gce-role \
type="gce" \
project_id="project-123456" \
policies="prod" \
bound_zone="us-central1-a" \
bound_instance_group="my-gce-group"
```
Users will login to Vault under roles (Vault-specific, unrelated to GCP IAM roles).
Roles are associated with an authentication type using the `type` parameter. Currently
`iam` or `gce` are acceptable values. The role also manages the [policies](/docs/concepts/policies.html)
the logged-in user will have and a set of constraints on authenticated users.
These are determined by the authenticating entity type and confirmed with GCP.
For the complete list of role options, please see the [API documentation](/api/auth/gcp/index.html#create-role).
The `gcp` auth method allows authentication against Vault using Google
credentials. It treats Google Cloud Platform (GCP) as a Trusted Third Party and
expects a [JSON Web Token][jwt] (JWT) signed by Google credentials from the
authenticating entity. This token can be generated through different GCP APIs
depending on the type of entity.
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.
## Authentication
These following examples assume the auth method is enabled at `/auth/gcp`
and use the CLI. For more complete documentation of parameters, see the
[HTTP API documentation](/api/auth/gcp/index.html#login).
There are two ways to login using the CLI:
### Via the CLI
### Client-provided JWT
The default path is `/gcp`. If this auth method was enabled at a different
path, specify `-path=/my-path` in the CLI.
In this case, you already have the GCE VM identity metadata token
or have obtained a IAM service account JWT, self-signed
or Google-signed using the GCP IAM API method
[projects.serviceAccounts.signJwt](https://cloud.google.com/iam/reference/rest/v1/projects.serviceAccounts/signJwt).
```sh
$ vault write auth/gcp/login \
role="dev-role" \
```text
$ vault login -method=gcp \
role="my-role" \
jwt="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```
* `role` is the role to login under
* `jwt` is the GCE metadata token or IAM service account token
In this example, the "role" is the name of a configured role. The "jwt" is a
self-signed or Google-signed JWT token obtained using the
[`signJwt`][signjwt-method] API call.
See docs on the [IAM workflow](#iam) or [GCE workflow](#gce) to see how to obtain this JWT.
Because the process to sign a service account JWT can be tedious, Vault includes
a CLI helper to generate the JWT token given the service account and parameters.
This process **only applies to `iam`-type roles!**
### (IAM ONLY) Client-side helper for service account JWT
Because the process to sign a service account JWT can be tedious,
we implemented a helper that can be run from client-side.
```sh
```text
$ vault login -method=gcp \
mount="gcp"
role="dev-role" \
jwt_exp
credentials="@/path/to/creds.json" \
project="project-for-authenticating-service-account" \
service-account="authenticating-service-account@project.iam.gserviceaccounts.com"
role="my-role" \
jwt_exp="15m" \
credentials=@path/to/credentials.json \
project="my-project" \
service-account="service-account@my-project.iam.gserviceaccounts.com"
```
This signs a properly formatted service account JWT for you and logs into Vault
directly. For more information, run `vault auth help gcp`.
Required Parameters:
- `role` `(string: <required>)` - The role with type=`iam` to login under.
Optional Parameters:
* `mount` (`string`: ``"gcp"`) - Name of the role.
* `jwt_exp` (`int`: `15`) - Number of minutes within which the JWT should expire.
This defaults to the default value used when creating a role, and should only be set
if set differently in the role (i.e. if the admin setting up your Vault server only accepts
JWTs that expire within < 15 min).
* `credentials`: If not provided, attempts to use Application Default Credentials.
These credentials are ONLY used to sign the service account JWT, i.e. call API
method [projects.serviceAccounts.signJwt](https://cloud.google.com/iam/reference/rest/v1/projects.serviceAccounts/signJwt),
and thus must have IAM permission `iam.serviceAccounts.signJWT` or role `iam.serviceAccountTokenCreator`
on the `service_account`, even if they are the same service account (**NOTE** this permission is not enabled by default).
```
* `service_account` `(string: `""`)`: Service account to sign JWT for i.e. login to Vault as
and is listed under roles `bound_service_accounts`. If not provided, uses `client_email`
from the credentials JSON. Only provide if the credentials are for a different account, acting as a "signer".
* `project`: Project of service account. If not provided, attempts to use `project_id` from the credentials JSON.
Fails if not found and not provided by Application Default Credentials. Only provide if the credentials are for a
different account, acting as a "signer".
## Authentication Workflow
### IAM
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 [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.
[![IAM Login Workflow](/assets/images/vault-gcp-iam-auth-workflow.svg)](/assets/images/vault-gcp-iam-auth-workflow.svg)
#### The `iam` Authentication Token
The expected format of the JWT payload is as follows:
```json
{
"sub" : "[SERVICE ACCOUNT IDENTIFIER]",
"aud" : "vault/[ROLE NAME]",
"exp" : "[EXPIRATION]"
}
```
- `[SERVICE ACCOUNT ID OR EMAIL]`: Either the email or the unique ID of a service account.
- `[ROLE NAME]`: Name of the role that this token will be used to login against. The full expected `aud` string should be "vault/$roleName".
- `[EXPIRATION]` : 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 (see `max_jwt_exp` parameter for creating a role). This defaults to 15 minutes and cannot be more than a hour.
**Note:** By default, we enforce a shorter `exp` period than the default length
for a given token (1 hour) in order to make reuse of tokens difficult. You can
customize this value for a given role but it will be capped at an hour.
To generate this token, we use the Google IAM API method [projects.serviceAccounts.signJwt](https://cloud.google.com/iam/reference/rest/v1/projects.serviceAccounts/signJwt).
See an [example of how to generate this token](#generating-iam-token).
### GCE
The Vault authentication workflow for GCE instances is as follows:
1. A client logins into a GCE instances and [obtains an instance identity metadata token](https://cloud.google.com/compute/docs/instances/verifying-instance-identity).
2. The client request to login using this token (a JWT) and gives a role name to Vault.
3. Vault uses 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. See the [authorization section](#authorization-workflow) to see how each type of role handles authorization.
[![GCE Login Workflow](/assets/images/vault-gcp-gce-auth-workflow.svg)](/assets/images/vault-gcp-gce-auth-workflow.svg)
#### The `gce` Authentication Token
The token can be obtained from the `service-accounts/default/identity` endpoint for a instance's
[metadata server](https://cloud.google.com/compute/docs/storing-retrieving-metadata). You can use the
[example of how to obtain an instance metadata token](#generating-gce-token) to get started.
Learn more about the JWT format from the
[documentation](https://cloud.google.com/compute/docs/instances/verifying-instance-identity#token_format)
for the identity metadata token. The params the user provides are:
* `[AUD]`: The full expected `aud` string should end in "vault/$roleName". Note that Google requires the `aud`
claim to contain a scheme or authority but Vault will only check for a suffix.
* `[FORMAT]`: MUST BE `full` for Vault. Format of the metadata token generated (`standard` or `full`).
### Examples for Obtaining Auth Tokens
#### Generating IAM Token
If you don't want to use the CLI helper, you can generate the JWT using the following methods.
**HTTP Request Example**
This uses [Google API HTTP annotation](https://github.com/googleapis/googleapis/blob/master/google/api/http.proto).
Note the `$PAYLOAD` must be a marshaled JSON string with escaped double quotes.
```sh
#!/bin/sh
# [START PARAMS]
ROLE="test-role"
PROJECT="project-123456"
SERVICE_ACCOUNT="my-account@project-123456.iam.gserviceaccount.com"
OAUTH_TOKEN=$(oauth2l header cloud-platform)
# [END PARAMS]
PAYLOAD=$(echo "{ \"aud\": \"vault/$ROLE\", \"sub\": \"$SERVICE_ACCOUNT\"}" | sed -e 's/"/\\&/g')
curl -H "$OAUTH_TOKEN" \
-H "Content-Type: application/json" \
-X POST -d "{\"payload\":\"$PAYLOAD\"}" https://iam.googleapis.com/v1/projects/$PROJECT/serviceAccounts/$SERVICE_ACCOUNT:signJwt
```
**Golang Example**
We use the Go OAuth2 libraries, GCP IAM API, and Vault API. The example generates a token valid for the `dev-role` role (as indicated by the `aud` field of `jwtPayload`).
```go
// Abbreviated imports to show libraries.
import (
vaultapi "github.com/hashicorp/vault/api"
"golang.org/x/oauth2"
"golang.org/x/oauth2/google"
"google.golang.org/api/iam/v1"
...
)
func main() {
// Start [PARAMS]
project := "project-123456"
serviceAccount := "myserviceaccount@project-123456.iam.gserviceaccount.com"
credsPath := "path/to/creds.json"
os.Setenv("VAULT_ADDR", "https://vault.mycompany.com")
defer os.Setenv("VAULT_ADDR", "")
// End [PARAMS]
// Start [GCP IAM Setup]
jsonBytes, err := ioutil.ReadFile(credsPath)
if err != nil {
log.Fatal(err)
}
config, err := google.JWTConfigFromJSON(jsonBytes, iam.CloudPlatformScope)
if err != nil {
log.Fatal(err)
}
httpClient := config.Client(oauth2.NoContext)
iamClient, err := iam.New(httpClient)
if err != nil {
log.Fatal(err)
}
// End [GCP IAM Setup]
// 1. Generate signed JWT using IAM.
resourceName := fmt.Sprintf("projects/%s/serviceAccounts/%s", project, serviceAccount)
jwtPayload := map[string]interface{}{
"aud": "vault/dev-role",
"sub": serviceAccount,
"exp": time.Now().Add(time.Minute * 10).Unix(),
}
payloadBytes, err := json.Marshal(jwtPayload)
if err != nil {
log.Fatal(err)
}
signJwtReq := &iam.SignJwtRequest{
Payload: string(payloadBytes),
}
resp, err := iamClient.Projects.ServiceAccounts.SignJwt(resourceName, signJwtReq).Do()
if err != nil {
log.Fatal(err)
}
// 2. Send signed JWT in login request to Vault.
vaultClient, err := vaultapi.NewClient(vaultapi.DefaultConfig())
if err != nil {
log.Fatal(err)
}
vaultResp, err := vaultClient.Logical().Write(
"auth/gcp/login",
map[string]interface{}{
"role": "test",
"jwt": resp.SignedJwt,
})
if err != nil {
log.Fatal(err)
}
// 3. Use auth token from response.
log.Println("Access token: %s", vaultResp.Auth.ClientToken)
vaultClient.SetToken(vaultResp.Auth.ClientToken)
// ...
}
```
#### Generating GCE Token
**HTTP Request Example**
This uses [Google API HTTP annotation](https://github.com/googleapis/googleapis/blob/master/google/api/http.proto)
and must be run on a GCE instance.
```sh
# [START PARAMS]
VAULT_ADDR="https://127.0.0.1:8200/"
ROLE="my-gce-role"
SERVICE_ACCOUNT="default" # replace with an instance's service account if needed
# [END PARAMS]
curl -H "Metadata-Flavor: Google"\
-G
--data-urlencode "audience=$VAULT_ADDR/vault/$ROLE"\
--data-urlencode "format=full" \
"http://metadata/computeMetadata/v1/instance/service-accounts/$SERVICE_ACCOUNT/identity"
```
## Authorization Workflow
For `gcp`, login is per-role. Each role has a specific set of restrictions that
an authorized entity must fit in order to login. These restrictions are specific
to the role type.
Currently supported role types are:
* `iam` (Supports both IAM and inference for GCE tokens)
* `gce` (Only supports GCE tokens)
Vault validates an authenticated entity against the role and uses the role to
determine information about the lease, including Vault policies assigned and
TTLs. For a full list of accepted restrictions, see [role API docs](/api/auth/gcp/index.html#create-role).
If a GCE token is provided for login under an `iam` role, the service account associated with the token
(`sub` claim) is inferred and used to login.
## Usage
### Via the CLI.
#### Enable GCP authentication in Vault
```sh
$ vault auth enable gcp
```
#### Configure the GCP Auth Method
```sh
$ vault write auth/gcp/config credentials=@path/to/creds.json
```
**Configuration**: This includes GCP credentials Vault will use these to make calls to
GCP APIs. If credentials are not configured or if the user explicitly sets the
config with no credentials, the Vault server will attempt to use
[Application Default Credentials](https://developers.google.com/identity/protocols/application-default-credentials)
as set on the Vault server.
See [API documentation](/api/auth/gcp/index.html#configure)
to learn more about parameters.
#### Create a role
```sh
$ vault write auth/gcp/role/dev-role \
type="iam" \
project_id="project-123456" \
policies="prod,dev" \
bound_service_accounts="serviceaccount1@project1234.iam.gserviceaccount.com,uuid123,..."
...
```
**Roles**: Roles are associated with an authentication type/entity and a set of
Vault [policies](/docs/concepts/policies.html). Roles are configured with constraints
specific to the authentication type, as well as overall constraints and
configuration for the generated auth tokens.
We also expose a helper path for updating the service accounts attached to an existing `iam` role:
```sh
$ vault write auth/gcp/role/iam-role/service-accounts \
add='serviceAccountToAdd,...' \
remove='serviceAccountToRemove,...' \
```
and for updating the labels attached to an existing `gce` role:
```sh
$ vault write auth/gcp/role/gce-role/labels \
add='label1:value1,foo:bar,...' \
remove='key1,key2,...' \
```
See [API docs](/api/auth/gcp/index.html#create-role) to view
parameters for role creation and updates.
#### Login to get a Vault Token
Once the backend is setup and roles are registered with the backend,
the user can login against a specific role.
```sh
$ vault write auth/gcp/login role='dev-role' jwt='eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
```
The `role` and `jwt` parameters are required. These map to the name of the
role to login against, and the signed JWT token for authenticating a role
respectively. The format of the provided JWT differs depending on the
authenticating entity.
This signs a properly formatted service account JWT and authenticates to Vault
directly. For details on each field, please run `vault auth help gcp`.
### Via the API
#### Enable GCP authentication in Vault
```sh
$ curl $VAULT_ADDR/v1/sys/auth/gcp -d '{ "type": "gcp" }'
```
#### Configure the GCP Auth Method
```sh
$ curl $VAULT_ADDR/v1/auth/gcp/config \
-d '{ "credentials": "{...}" }'
```
#### Create a role
```sh
$ curl $VAULT_ADDR/v1/auth/gcp/role/dev-role \
-d '{ "type": "iam", "project_id": "project-123456", ...}'
```
#### Login to get a Vault Token
The endpoint for the GCP login is `auth/gcp/login`.
The `gcp` mountpoint value in the url is the default mountpoint value.
If you have mounted the `gcp` backend with a different mountpoint, use that value.
The `role` and `jwt` should be sent in the POST body encoded as JSON.
```sh
$ curl $VAULT_ADDR/v1/auth/gcp/login \
-d '{ "role": "dev-role", "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }'
```text
$ curl \
--request POST \
--data '{"role":"my-role", "jwt":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}' \
http://127.0.0.1:8200/v1/auth/gcp/login
```
The response will be in JSON. For example:
```json
```javascript
{
"auth":{
"client_token":"f33f8c72-924e-11f8-cb43-ac59d697597c",
"accessor":"0e9e354a-520f-df04-6867-ee81cae3d42d",
"policies":[
"default",
"dev",
"prod"
],
"metadata":{
"role": "dev-role",
"service_account_email": "dev1@project-123456.iam.gserviceaccount.com",
"service_account_id": "111111111111111111111"
},
"lease_duration":2764800,
"renewable":true
"auth": {
"client_token": "f33f8c72-924e-11f8-cb43-ac59d697597c",
"accessor": "0e9e354a-520f-df04-6867-ee81cae3d42d",
"policies": [
"default",
"dev",
"prod"
],
"metadata": {
"role": "my-role",
"service_account_email": "dev1@project-123456.iam.gserviceaccount.com",
"service_account_id": "111111111111111111111"
},
...
"lease_duration": 2764800,
"renewable": true
}
}
```
### Contributing
## Configuration
This plugin is developed in a separate GitHub repository: [`hashicorp/vault-plugin-auth-gcp`](https://github.com/hashicorp/vault-plugin-auth-gcp). Please file all feature requests, bugs, and pull requests specific to the GCP plugin under that repository.
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" \
project_id="my-project" \
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" \
project_id="my-project" \
policies="dev,prod" \
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
```
## 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 implementation 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](/assets/images/vault-gcp-iam-auth-workflow.svg)](/assets/images/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](/assets/images/vault-gcp-gce-auth-workflow.svg)](/assets/images/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.
## Obtaining JWT Tokens
Vault expects a signed JWT token to verify against. There are a few ways to
acquire a JWT token.
### Generating IAM Tokens
Vault includes a CLI helper for generating the signed JWT token and submitting
it to Vault for `iam`-type roles. If you want to generate the JWT token
yourself, follow this section.
#### Shell Example
The expected format of the JWT request payload is:
```javascript
{
"sub": "$SERVICE_ACCOUNT",
"aud": "vault/$ROLE",
"exp": "$EXPIRATION" // optional
}
```
If specified, the 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
```text
gcloud beta iam service-accounts sign-jwt credentials.json - \
--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"
SERVICE_ACCOUNT="service-account@my-project.iam.gserviceaccount.com"
curl \
--header "Metadata-Flavor: Google" \
--get \
--data-urlencode "aud=http://vault/${ROLE}" \
--data-urlencode "format=full" \
"http://metadata/computeMetadata/v1/instance/service-accounts/${SERVICE_ACCOUNT}/identity"
```
## API
The GCP Auth Plugin has a full HTTP API. Please see the
[API docs](/api/auth/gcp/index.html) for more details.
[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
[instance-identity]: https://cloud.google.com/compute/docs/instances/verifying-instance-identity

2
website/source/docs/secrets/gcp/index.html.md
View File

@ -3,7 +3,7 @@ layout: "docs"
page_title: "Google Cloud - Secrets Engines"
sidebar_current: "docs-secrets-gcp"
description: |-
The Google Cloud Vault secrets engine dynamically generates Google Cloud
The Google Cloud secrets engine for Vault dynamically generates Google Cloud
service account keys and OAuth tokens based on IAM policies.
---