From a379989da47f6a342f2890bd4f2cc14c455e2c2b Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Wed, 11 Jul 2018 15:52:22 -0400 Subject: [PATCH] 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. --- website/data/news.yml | 3 +- website/source/api/auth/gcp/index.html.md | 390 ++++----- website/source/api/secret/gcp/index.html.md | 8 +- .../api/system/plugins-reload-backend.html.md | 4 +- .../images/vault-gcp-gce-auth-workflow.svg | 206 +---- .../images/vault-gcp-iam-auth-workflow.svg | 164 +--- website/source/docs/auth/gcp.html.md | 740 ++++++------------ website/source/docs/secrets/gcp/index.html.md | 2 +- 8 files changed, 545 insertions(+), 972 deletions(-) diff --git a/website/data/news.yml b/website/data/news.yml index 378b58d2e..d3a6131c1 100644 --- a/website/data/news.yml +++ b/website/data/news.yml @@ -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" diff --git a/website/source/api/auth/gcp/index.html.md b/website/source/api/auth/gcp/index.html.md index bd5097e36..c49860388 100644 --- a/website/source/api/auth/gcp/index.html.md +++ b/website/source/api/auth/gcp/index.html.md @@ -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: )` - Name of the role. -- `type` `(string: )` - 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: )` - The name of the role. + +- `type` `(string: )` - 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: )` - 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: )` - 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: )` - 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: )` - 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: )` - 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: )` - 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: )` - Name of the role. +- `name` `(string: )` - 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: )` - Name of the role. +- `role` `(string: )` - 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: )` - The name of the role against which the login + is being attempted. + +- `jwt` `(string: )` - 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 diff --git a/website/source/api/secret/gcp/index.html.md b/website/source/api/secret/gcp/index.html.md index 3f54c6c1f..d2699cbf1 100644 --- a/website/source/api/secret/gcp/index.html.md +++ b/website/source/api/secret/gcp/index.html.md @@ -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). diff --git a/website/source/api/system/plugins-reload-backend.html.md b/website/source/api/system/plugins-reload-backend.html.md index d2035f6ac..c81287935 100644 --- a/website/source/api/system/plugins-reload-backend.html.md +++ b/website/source/api/system/plugins-reload-backend.html.md @@ -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 diff --git a/website/source/assets/images/vault-gcp-gce-auth-workflow.svg b/website/source/assets/images/vault-gcp-gce-auth-workflow.svg index 0a376bbd9..e994e3cec 100644 --- a/website/source/assets/images/vault-gcp-gce-auth-workflow.svg +++ b/website/source/assets/images/vault-gcp-gce-auth-workflow.svg @@ -1,170 +1,38 @@ - - - - Sequence Diagram 1@3x - Created with Sketch. - - - - - - - - - - - - - - - - - - - - Instance - - - Compute Engine - - - - - - - - - - - - - - - - - - - - - - - - Metadata Server - - - Compute Engine - - - - - - - - - - - - - - - - - - - - - - - - Google - OAuth2 API - - - - - - - - - Hashicorp Vault - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + - \ No newline at end of file + + + + + + + + + + + + + + + + + + + + + + diff --git a/website/source/assets/images/vault-gcp-iam-auth-workflow.svg b/website/source/assets/images/vault-gcp-iam-auth-workflow.svg index 295e42d65..a36c6e0a1 100644 --- a/website/source/assets/images/vault-gcp-iam-auth-workflow.svg +++ b/website/source/assets/images/vault-gcp-iam-auth-workflow.svg @@ -1,134 +1,32 @@ - - - - Sequence Diagram 2@3x - Created with Sketch. - - - - - - - - - - - - - - - - - - - Hashicorp - Vault - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Cloud IAM - - - - - - - - - - - - - - Developer - - - - + + + + + + + + + + + + + + + - \ No newline at end of file + + + + + + + + + + + + + + + + diff --git a/website/source/docs/auth/gcp.html.md b/website/source/docs/auth/gcp.html.md index d6e46d619..0568aa94e 100644 --- a/website/source/docs/auth/gcp.html.md +++ b/website/source/docs/auth/gcp.html.md @@ -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: )` - 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 diff --git a/website/source/docs/secrets/gcp/index.html.md b/website/source/docs/secrets/gcp/index.html.md index 023c01756..07b8597b0 100644 --- a/website/source/docs/secrets/gcp/index.html.md +++ b/website/source/docs/secrets/gcp/index.html.md @@ -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. ---