Seth Vargo
Jim Kalafut
parent
21dc5a72bf
commit
46cbfb0e4b
|
|
@ -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 \
|
||||
|
|
|
|||
Loading…
Reference in a new issue