From 0e0f356a47ccdfd5074c383791e2a822783aca39 Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Tue, 8 Jan 2019 11:51:37 -0500 Subject: [PATCH] Fix formatting (#6009) The new markdown parser is less forgiving --- website/source/docs/auth/gcp.html.md | 68 ++++++++++++++-------------- 1 file changed, 35 insertions(+), 33 deletions(-) diff --git a/website/source/docs/auth/gcp.html.md b/website/source/docs/auth/gcp.html.md index e67ed5021eb8..c2fa1b371482 100644 --- a/website/source/docs/auth/gcp.html.md +++ b/website/source/docs/auth/gcp.html.md @@ -19,7 +19,7 @@ for authentication of: * 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"`) +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 @@ -32,12 +32,12 @@ repository. 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 +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 +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. @@ -45,15 +45,15 @@ To authenticate, you will need two things: ### 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. #### 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 +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 @@ -65,21 +65,23 @@ $ vault login -method=gcp \ credentials=@path/to/signer/credentials.json \ ``` -Note that `credentials` must have signJwt permissions on `service_account`. +Note that `credentials` must have signJwt permissions on `service_account`. + +*Optional Fields* -*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. + +* `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. +from the API or by yourself, you can run the following command to +login. ```text @@ -88,10 +90,10 @@ $ vault write -field=token auth/gcp/login role="my-role" jwt="eyJhbGciOiJIUzI1Ni #### Obtaining `gce` JWT (Metadata) -GCE tokens are obtained from a GCE instance's own metadata server endpoint, -`service-accounts/default/identity`. +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.**. +**You must run these example commands from the GCE instance.**. ```text ROLE="my-gce-role" @@ -105,10 +107,10 @@ curl \ "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 +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 @@ -195,15 +197,15 @@ https://www.googleapis.com/auth/cloud-platform ### Vault Identity Features -This section describes features related to Vault's +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 +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 +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 @@ -219,9 +221,9 @@ will be added: ``` Note this is opt-in as it requires a project-level or organizational-level -Google IAM permission `resourcemanager.projects.get`. +Google IAM permission `resourcemanager.projects.get`. -## Appendixes +## Appendixes ### Implementation Details and Workflow @@ -275,9 +277,9 @@ another cloud provider. ### Generating IAM JWT 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. +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 @@ -291,8 +293,8 @@ Vault requires the following minimum claim set: } ``` -For the API method, expiration is optional and will default to an hour. -If specified, 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. @@ -316,7 +318,7 @@ curl \ #### gcloud Example -You can also do this through the (currently beta) gcloud command. +You can also do this through the (currently beta) gcloud command. ```text $ gcloud beta iam service-accounts sign-jwt $INPUT_JWT_CLAIMS $OUTPUT_JWT_FILE \