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

@@ -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: <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".
@@ -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: <required for iam>)` - A comma-separated
+- `bound_service_accounts` `(array: <required for iam>)` - An array of 
-  list of service account emails or IDs that login is restricted to. If set to
+   service account emails or IDs that login is restricted to,
-  `*`, all service accounts are allowed (role will still be bound by project).
+   either directly or through an associated instance. If set to
-  Will be inferred from service account used to issue metadata token for GCE
+  `*`, all service accounts are allowed (you can bind this further using
-  instances.
+  `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"

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
+The `gcp` auth method allows Google Cloud Platform (GCP) entities to
-credentials. It treats Google Cloud Platform (GCP) as a Trusted Third Party and
+authenticate to Vault. Vault treats GCP as a Trusted Third Party and
-expects a [JSON Web Token][jwt] (JWT) signed by Google credentials from the
+verifies authenticating entities against GCP APIs. This backend allows
-authenticating entity. This token can be generated through different GCP APIs
+for authentication of:
-depending on the type of entity.
+
+* 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.
+path, specify `-path=/my-path` in the CLI. 
-
+The backend takes a signed [JSON Web Token][jwt] (JWT) as proof-of-identity.
-```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.
 
+#### 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.
+a CLI helper that handles obtaining a properly-formatted and signed JWT on your
-This process **only applies to `iam`-type roles!**
+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" \
+    service_account="authenticating-account@my-project.iam.gserviceaccounts.com"
-    credentials=@path/to/credentials.json \
     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
+Note that `credentials` must have signJwt permissions on `service_account`. 
-directly. For details on each field, please run `vault auth help gcp`.
 
+*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:
+See [API docs][api-docs] for expected response.
-
-```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
-  }
-}
-```
 
 ## 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
+This describes how to use the GCP IAM [API method][signjwt-method] directly
-acquire a JWT token.
+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
+Vault requires the following minimum claim set:
-it to Vault for `iam`-type roles. If you want to generate the JWT token
-yourself, follow this section.
 
-#### Shell Example
+```json
-
-The expected format of the JWT request payload is:
-
-```javascript
 {
-  "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