From 94c03d1072db4572bbcb17919b6d4c28a5e17198 Mon Sep 17 00:00:00 2001 From: emily Date: Mon, 10 Dec 2018 12:54:18 -0800 Subject: [PATCH] Update GCP auth BE docs (#5753) Documented changes from https://github.com/hashicorp/vault-plugin-auth-gcp/pull/55 * Deprecating `project_id` for `bound_projects` and making it optional * Deprecating `google_certs_endpoint` (unused) * Adding group aliases Also, some general reformatting --- website/source/api/auth/gcp/index.html.md | 28 +-- website/source/docs/auth/gcp.html.md | 200 ++++++++++++++-------- 2 files changed, 146 insertions(+), 82 deletions(-) diff --git a/website/source/api/auth/gcp/index.html.md b/website/source/api/auth/gcp/index.html.md index a66071f72..7900696cc 100644 --- a/website/source/api/auth/gcp/index.html.md +++ b/website/source/api/auth/gcp/index.html.md @@ -45,11 +45,6 @@ to confirm signed JWTs passed in during login. The project must have the `iam.googleapis.com` API [enabled](https://console.cloud.google.com/flows/enableapi?apiid=iam.googleapis.com). -- `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 @@ -133,9 +128,6 @@ entities attempting to login. 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". @@ -153,12 +145,21 @@ entities attempting to login. - `policies` `(array: [default])` - The list of policies to be set on tokens issued using this role. -- `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. +- `bound_service_accounts` `(array: )` - An array of + service account emails or IDs that login is restricted to, + either directly or through an associated instance. If set to + `*`, all service accounts are allowed (you can bind this further using + `bound_projects`.) + +- `bound_projects` `(array: [])` - An array of GCP project IDs. Only entities + belonging to this project can authenticate under the role. +- `add_group_aliases` `(bool: false)` - If true, any auth token + generated under this token will have associated group aliases, namely + `project-$PROJECT_ID`, `folder-$PROJECT_ID`, and `organization-$ORG_ID` + for the entities project and all its folder or organization ancestors. This + requires Vault to have IAM permission `resourcemanager.projects.get`. + #### `iam`-only Parameters The following parameters are only valid when the role is of type `"iam"`: @@ -486,6 +487,7 @@ $ curl \ "prod" ], "metadata": { + "project_id": "my-project", "role": "my-role", "service_account_email": "dev1@project-123456.iam.gserviceaccount.com", "service_account_id": "111111111111111111111" diff --git a/website/source/docs/auth/gcp.html.md b/website/source/docs/auth/gcp.html.md index 510922c9f..e67ed5021 100644 --- a/website/source/docs/auth/gcp.html.md +++ b/website/source/docs/auth/gcp.html.md @@ -10,11 +10,17 @@ description: |- # Google Cloud Auth Method -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. +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: + +* 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 plugin is developed in a separate GitHub repository at [`hashicorp/vault-plugin-auth-gcp`](https://github.com/hashicorp/vault-plugin-auth-gcp), @@ -22,39 +28,87 @@ 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 +## Quick Start -### Via the CLI +To authenticate, you will need two things: + +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 CLI The default path is `/gcp`. If this auth method was enabled at a different -path, specify `-path=/my-path` in the CLI. - -```text -$ vault login -method=gcp \ - role="my-role" \ - jwt="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." -``` - -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. +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 to generate the JWT token given the service account and parameters. -This process **only applies to `iam`-type roles!** +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. ```text $ vault login -method=gcp \ role="my-role" \ - jwt_exp="15m" \ - credentials=@path/to/credentials.json \ + service_account="authenticating-account@my-project.iam.gserviceaccounts.com" project="my-project" \ - service_account="service-account@my-project.iam.gserviceaccounts.com" + jwt_exp="15m" \ + credentials=@path/to/signer/credentials.json \ ``` -This signs a properly formatted service account JWT and authenticates to Vault -directly. For details on each field, please run `vault auth help gcp`. +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. + + +```text +$ 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. + ### Via the API ```text @@ -64,28 +118,7 @@ $ curl \ http://127.0.0.1:8200/v1/auth/gcp/login ``` -The response will be in JSON. For example: - -```javascript -{ - "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 - } -} -``` +See [API docs][api-docs] for expected response. ## Configuration @@ -117,7 +150,6 @@ management tool. ```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" ``` @@ -127,8 +159,8 @@ management tool. ```text $ vault write auth/gcp/role/my-gce-role \ type="gce" \ - project_id="my-project" \ policies="dev,prod" \ + bound_projects="my-project1,my-project2" \ bound_zones="us-east1-b" \ bound_labels="foo:bar,zip:zap" ``` @@ -161,14 +193,44 @@ minimum scope(s): https://www.googleapis.com/auth/cloud-platform ``` -## Workflow +### Vault Identity Features + +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. + +#### Group Aliases + +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: + +```javascript +[ + "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 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 +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: @@ -189,7 +251,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 @@ -210,30 +272,27 @@ 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. -## Obtaining JWT Tokens +### Generating IAM JWT -Vault expects a signed JWT token to verify against. There are a few ways to -acquire a JWT token. +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. -### Generating IAM Tokens +#### curl -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. +Vault requires the following minimum claim set: -#### Shell Example - -The expected format of the JWT request payload is: - -```javascript +```json { - "sub": "$SERVICE_ACCOUNT", + "sub": "$SERVICE_ACCOUNT_EMAIL_OR_ID", "aud": "vault/$ROLE", - "exp": "$EXPIRATION" // optional + "exp": "$EXPIRATION" } ``` -If specified, the expiration must be a +For the API method, expiration is optional and will default to an hour. +If specified, 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. @@ -257,8 +316,10 @@ curl \ #### gcloud Example +You can also do this through the (currently beta) gcloud command. + ```text -$ gcloud beta iam service-accounts sign-jwt credentials.json - \ +$ gcloud beta iam service-accounts sign-jwt $INPUT_JWT_CLAIMS $OUTPUT_JWT_FILE \ --iam-account=service-account@my-project.iam.gserviceaccount.com \ --project=my-project ``` @@ -295,4 +356,5 @@ The GCP Auth Plugin has a full HTTP API. Please see the [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 +[identity-group-aliases]: /api/secret/identity/group-alias.html [instance-identity]: https://cloud.google.com/compute/docs/instances/verifying-instance-identity