From 41d2e31266baf5b1c84af601dac330beb7fa3cba Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Thu, 10 Jan 2019 13:05:21 -0500 Subject: [PATCH] Simplify permission requirements for GCP things (#6012) --- website/source/docs/auth/gcp.html.md | 182 +++++++----------- website/source/docs/secrets/gcp/index.html.md | 3 +- .../source/docs/secrets/gcpkms/index.html.md | 27 +-- 3 files changed, 76 insertions(+), 136 deletions(-) diff --git a/website/source/docs/auth/gcp.html.md b/website/source/docs/auth/gcp.html.md index c2fa1b3714..6fcfd1637c 100644 --- a/website/source/docs/auth/gcp.html.md +++ b/website/source/docs/auth/gcp.html.md @@ -10,106 +10,52 @@ description: |- # Google Cloud Auth Method -The `gcp` auth method allows Google Cloud Platform (GCP) entities to -authenticate to Vault. Vault treats GCP as a Trusted Third Party and -verifies authenticating entities against GCP APIs. This backend allows -for authentication of: +The `gcp` auth method allows Google Cloud Platform entities to authenticate to +Vault. Vault treats Google Cloud as a trusted third party and verifies +authenticating entities against the Google Cloud APIs. This backend allows for +authentication of: -* IAM service accounts -* Google Compute Engine (GCE) instances +- Google Cloud IAM service accounts +- Google Compute Engine (GCE) instances -**NOTE**: This backend focuses on identities specific to Google Cloud and -does not support authenticating Google users (i.e. `type: "authorized_user"`) -or OAuth against Google +This backend focuses on identities specific to Google _Cloud_ and does not +support authenticating arbitrary Google or G Suite users or generic OAuth +against Google. This plugin is developed in a separate GitHub repository at -[`hashicorp/vault-plugin-auth-gcp`](https://github.com/hashicorp/vault-plugin-auth-gcp), +[hashicorp/vault-plugin-auth-gcp][repo], but is automatically bundled in Vault releases. Please file all feature requests, bugs, and pull requests specific to the GCP plugin under that repository. -## Quick Start -To authenticate, you will need two things: +## Authenticate -1. Proof-of-identity: - * Service Account: A signed [JSON Web Token][jwt] (JWT), or GCP credentials - with permissions to sign a JWT (see [`signJwt`][signjwt-method] IAM API - method) for this service account - * Access to a metadata server for a GCE instance -1. Name of a `role`, a binding of Vault policies and authZ - restrictions preconfigured for the GCP auth backend that - an entity authenticates under. Roles are either type `iam`, which - supports either type of entity, or `gce`, which support only GCE instances. +### Via the CLI Helper -### Via CLI - -The default path is `/gcp`. If this auth method was enabled at a different -path, specify `-path=/my-path` in the CLI. -The backend takes a signed [JSON Web Token][jwt] (JWT) as proof-of-identity. - -#### Generate `iam` JWT and Login - -Because the process to sign a service account JWT can be tedious, Vault includes -a CLI helper that handles obtaining a properly-formatted and signed JWT on your -client before sending an actual request to the Vault server. This process -**only applies to `iam`-type roles!** For GCE instances, the JWT is -automatically generated by Google and exposed as metadata. +Vault includes a CLI helper that obtains a signed JWT locally and sends the +request to Vault. This helper is only available for IAM-type roles. ```text $ vault login -method=gcp \ role="my-role" \ - service_account="authenticating-account@my-project.iam.gserviceaccounts.com" + service_account="authenticating-account@my-project.iam.gserviceaccounts.com" \ project="my-project" \ jwt_exp="15m" \ - credentials=@path/to/signer/credentials.json \ + credentials=@path/to/signer/credentials.json ``` -Note that `credentials` must have signJwt permissions on `service_account`. - -*Optional Fields* - -* `credentials` can be omitted to default to Application Default Credentials. - -* `service_account` or `project` can be omitted and Vault will attempt to - default to values in `credentials`. However, Vault will return an error if - the `credentials` are not a valid service account key file. - -For more details on each field, please run `vault auth help gcp`. - -#### Login With Existing JWT - -If you already have an existing service account JWT that you generated -from the API or by yourself, you can run the following command to -login. +For more usage information, run `vault auth help gcp`. +### Via the CLI ```text -$ vault write -field=token auth/gcp/login role="my-role" jwt="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." +$ vault write -field=token auth/gcp/login \ + role="my-role" \ + jwt="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." ``` -#### Obtaining `gce` JWT (Metadata) - -GCE tokens are obtained from a GCE instance's own metadata server endpoint, -`service-accounts/default/identity`. - -**You must run these example commands from the GCE instance.**. - -```text -ROLE="my-gce-role" -SERVICE_ACCOUNT="default" - -curl \ - --header "Metadata-Flavor: Google" \ - --get \ - --data-urlencode "audience=http://vault/${ROLE}" \ - --data-urlencode "format=full" \ - "http://metadata/computeMetadata/v1/instance/service-accounts/${SERVICE_ACCOUNT}/identity" -``` - -Since instances currently only support one service account, you can use -`default` as we do to refer to the associated service account. You can also -use the actual service account email or ID. +See [Generating JWTs](#generating-jwts) for ways to obtain the JWT token. ### Via the API @@ -171,7 +117,7 @@ management tool. [API documentation][api-docs]. -### Google Cloud Authentication +## 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 @@ -188,51 +134,57 @@ 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): +To use this auth method, the service account must have the following minimum +scope: ```text https://www.googleapis.com/auth/cloud-platform ``` -### Vault Identity Features +### Required Permissions -This section describes features related to Vault's -[Identity](/docs/secrets/identity/index.html) -system. Since the Identity system was released after the initial GCP auth -backend plugin was released, this will generally cover features -we have added in newer releases of the plugin. +The credentials given to Vault must have the following roles: -#### Group Aliases +```text +roles/iam.serviceAccountKeyAdmin +roles/browser +``` -Roles now have a `add_group_aliases` boolean parameter that adds -[Group Aliases][identity-group-aliases] to the auth response. For example, -for a project `$PROJECT_ID`, in subfolder `$SUBFOLDER_ID`, -in folder `$FOLDER_ID`, in organization `$ORG_ID`, the following group aliases -will be added: +Note that this is the permission **given to the Vault servers**. The IAM +service account or GCE instance that is authenticating _against_ Vault must +have the following role: -```javascript +```text +roles/iam.serviceAccountTokenCreator +``` + + +## Group Aliases + +As of Vault 1.0, roles can specify an `add_group_aliases` boolean parameter +that adds [group aliases][identity-group-aliases] to the auth response. These +aliases can aid in building reusable policies since they are available as +interpolated values in Vault's policy engine. Once enabled, the auth response +will include the following aliases: + +```json [ - "project-$PROJECT_ID", - "folder-$SUBFOLDER_ID", - "folder-$FOLDER_ID", - "organization-$ORG_ID" + "project-$PROJECT_ID", + "folder-$SUBFOLDER_ID", + "folder-$FOLDER_ID", + "organization-$ORG_ID" ] ``` -Note this is opt-in as it requires a project-level or organizational-level -Google IAM permission `resourcemanager.projects.get`. -## Appendixes - -### Implementation Details and Workflow +## Implementation Details This section describes the implementation details for how Vault communicates with Google Cloud to authenticate and authorize JWT tokens. This information is provided for those who are curious, but these details are not required knowledge for using the auth method. -#### IAM Login +### IAM Login IAM login applies only to roles of type `iam`. The Vault authentication workflow for IAM service accounts looks like this: @@ -253,7 +205,7 @@ for IAM service accounts looks like this: 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 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 @@ -274,14 +226,20 @@ another cloud provider. the instance matches the bound zones, regions, or instance groups. If that is successful, a Vault token with the proper policies is returned. -### Generating IAM JWT + +## Generating JWTs + +This section details the various methods and examples for obtaining JWT +tokens. + +### IAM This describes how to use the GCP IAM [API method][signjwt-method] directly to generate the signed JWT with the claims that Vault expects. Note the CLI does this process for you and is much easier, and that there is very little reason to do this yourself. -#### curl +#### curl Example Vault requires the following minimum claim set: @@ -307,12 +265,13 @@ ROLE="my-role" PROJECT="my-project" SERVICE_ACCOUNT="service-account@my-project.iam.gserviceaccount.com" OAUTH_TOKEN="$(oauth2l header cloud-platform)" +JWT_CLAIM="{\\\"aud\\\":\\\"vault/${ROLE}\\\", \\\"sub\\\": \\\"${SERVICE_ACCOUNT}\\\"}" curl \ --header "${OAUTH_TOKEN}" \ --header "Content-Type: application/json" \ --request POST \ - --data "{\"aud\":\"vault/${ROLE}\", \"sub\": \"${SERVICE_ACCOUNT}\"}" \ + --data "{\"payload\": \"${JWT_CLAIM}\"}" \ "https://iam.googleapis.com/v1/projects/${PROJECT}/serviceAccounts/${SERVICE_ACCOUNT}:signJwt" ``` @@ -331,11 +290,13 @@ $ gcloud beta iam service-accounts sign-jwt $INPUT_JWT_CLAIMS $OUTPUT_JWT_FILE \ 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 -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. +GCE tokens **can only be generated from a GCE instance**. The JWT token can be +obtained from the `service-accounts/default/identity` endpoint for a +instance's metadata server. + +#### curl Example ```text ROLE="my-gce-role" @@ -360,3 +321,4 @@ The GCP Auth Plugin has a full HTTP API. Please see the [api-docs]: /api/auth/gcp/index.html [identity-group-aliases]: /api/secret/identity/group-alias.html [instance-identity]: https://cloud.google.com/compute/docs/instances/verifying-instance-identity +[repo]: https://github.com/hashicorp/vault-plugin-auth-gcp diff --git a/website/source/docs/secrets/gcp/index.html.md b/website/source/docs/secrets/gcp/index.html.md index a0b0f8a876..a4f2ddb8fd 100644 --- a/website/source/docs/secrets/gcp/index.html.md +++ b/website/source/docs/secrets/gcp/index.html.md @@ -139,7 +139,7 @@ to GCP APIs: ```sh $ curl -H "Authorization: Bearer ya29.c.ElodBmNPwHUNY5gcBpnXcE4ywG4w1k..." -``` +``` ### Service Account Keys @@ -288,7 +288,6 @@ minimum scope(s): ```text https://www.googleapis.com/auth/cloud-platform -https://www.googleapis.com/auth/iam ``` ### Required Permissions diff --git a/website/source/docs/secrets/gcpkms/index.html.md b/website/source/docs/secrets/gcpkms/index.html.md index 63397a1826..fa56407d5f 100644 --- a/website/source/docs/secrets/gcpkms/index.html.md +++ b/website/source/docs/secrets/gcpkms/index.html.md @@ -353,7 +353,7 @@ on [Google Compute Engine][gce] or [Google Kubernetes Engine][gke] 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 +To use this secrets engine, the service account must have the following minimum scope(s): ```text @@ -362,28 +362,7 @@ https://www.googleapis.com/auth/kms ### Required Permissions -The credentials given to Vault must have the following permissions: - -```text -locations.keyRings.create -locations.keyRings.cryptoKeys.list -locations.keyRings.cryptoKeys.get -locations.keyRings.cryptoKeys.create -locations.keyRings.cryptoKeys.encrypt -locations.keyRings.cryptoKeys.decrypt -locations.keyRings.cryptoKeys.patch -locations.keyRings.cryptoKeys.updatePrimaryVersion -locations.keyRings.cryptoKeys.cryptoKeyVersions.list -locations.keyRings.cryptoKeys.cryptoKeyVersions.get -locations.keyRings.cryptoKeys.cryptoKeyVersions.create -locations.keyRings.cryptoKeys.cryptoKeyVersions.patch -locations.keyRings.cryptoKeys.cryptoKeyVersions.destroy -locations.keyRings.cryptoKeys.cryptoKeyVersions.asymmetricDecrypt -locations.keyRings.cryptoKeys.cryptoKeyVersions.asymmetricSign -locations.keyRings.cryptoKeys.cryptoKeyVersions.getPublicKey -``` - -For simplicity, you can use this role instead: +The credentials given to Vault must have the following role: ```text roles/cloudkms.admin @@ -403,7 +382,7 @@ To sign and verify, you only need the following permissions: roles/cloudkms.signerVerifier ``` -For more information, please see the [Google Cloud KMS IAM documentation][kms-iam] +For more information, please see the [Google Cloud KMS IAM documentation][kms-iam]. ## FAQ