-
Notifications
You must be signed in to change notification settings - Fork 4.2k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Documented changes from hashicorp/vault-plugin-auth-gcp#55 * Deprecating `project_id` for `bound_projects` and making it optional * Deprecating `google_certs_endpoint` (unused) * Adding group aliases Also, some general reformatting
- Loading branch information
Showing
2 changed files
with
145 additions
and
81 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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 | ||
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: <required for iam>)` - 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": "[email protected]", | ||
"service_account_id": "111111111111111111111" | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -10,51 +10,105 @@ 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), | ||
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 | ||
|
||
To authenticate, you will need two things: | ||
|
||
### Via the CLI | ||
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. | ||
|
||
#### 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. | ||
|
||
```text | ||
$ vault login -method=gcp \ | ||
role="my-role" \ | ||
jwt="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." | ||
service_account="[email protected]" | ||
project="my-project" \ | ||
jwt_exp="15m" \ | ||
credentials=@path/to/signer/credentials.json \ | ||
``` | ||
|
||
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. | ||
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. | ||
|
||
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!** | ||
|
||
```text | ||
$ vault login -method=gcp \ | ||
role="my-role" \ | ||
jwt_exp="15m" \ | ||
credentials=@path/to/credentials.json \ | ||
project="my-project" \ | ||
service_account="[email protected]" | ||
$ vault write -field=token auth/gcp/login role="my-role" jwt="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." | ||
``` | ||
|
||
This signs a properly formatted service account JWT and authenticates to Vault | ||
directly. For details on each field, please run `vault auth help gcp`. | ||
#### 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": "[email protected]", | ||
"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="[email protected]" | ||
``` | ||
|
@@ -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 | ||
|
||
Vault expects a signed JWT token to verify against. There are a few ways to | ||
acquire a JWT token. | ||
|
||
### Generating IAM Tokens | ||
### Generating IAM JWT | ||
|
||
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. | ||
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. | ||
|
||
#### Shell Example | ||
#### curl | ||
|
||
The expected format of the JWT request payload is: | ||
Vault requires the following minimum claim set: | ||
|
||
```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 \ | ||
[email protected] \ | ||
--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 |