luxolus
/
open-vault
2
0
Fork 0
Code Issues 1 Pull Requests Releases Activity

Simplify permission requirements for GCP things (#6012)

This commit is contained in:
Seth Vargo 2019-01-10 13:05:21 -05:00 committed by Brian Kassouf
parent 4bb4166276
commit e726f13957
3 changed files with 76 additions and 136 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

182
website/source/docs/auth/gcp.html.md
View File

@ -10,106 +10,52 @@ description: |-
# Google Cloud Auth Method
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:
The `gcp` auth method allows Google Cloud Platform entities to authenticate to
Vault. Vault treats Google Cloud as a trusted third party and verifies
authenticating entities against the Google Cloud APIs. This backend allows for
authentication of:
* IAM service accounts
* Google Compute Engine (GCE) instances
- Google Cloud 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 backend focuses on identities specific to Google _Cloud_ and does not
support authenticating arbitrary Google or G Suite users or generic 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),
[hashicorp/vault-plugin-auth-gcp][repo],
but is automatically bundled in Vault releases. Please file all feature
requests, bugs, and pull requests specific to the GCP plugin under that
repository.
## Quick Start
To authenticate, you will need two things:
## Authenticate
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 the CLI Helper
### Via CLI
The default path is `/gcp`. If this auth method was enabled at a different
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.
Vault includes a CLI helper that obtains a signed JWT locally and sends the
request to Vault. This helper is only available for IAM-type roles.
```text
$ vault login -method=gcp \
role="my-role" \
service_account="authenticating-account@my-project.iam.gserviceaccounts.com"
service_account="authenticating-account@my-project.iam.gserviceaccounts.com" \
project="my-project" \
jwt_exp="15m" \
credentials=@path/to/signer/credentials.json \
credentials=@path/to/signer/credentials.json
```
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.
For more usage information, run `vault auth help gcp`.
### Via the CLI
```text
$ vault write -field=token auth/gcp/login role="my-role" jwt="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
$ 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.
See [Generating JWTs](#generating-jwts) for ways to obtain the JWT token.
### Via the API
@ -171,7 +117,7 @@ management tool.
[API documentation][api-docs].
### Google Cloud Authentication
## Authentication
The Google Cloud Vault auth method uses the official Google Cloud Golang SDK.
This means it supports the common ways of [providing credentials to Google
@ -188,51 +134,57 @@ default service account credentials are used.
For more information on service accounts, please see the [Google Cloud Service
Accounts documentation][service-accounts].
To use this storage backend, the service account must have the following
minimum scope(s):
To use this auth method, the service account must have the following minimum
scope:
```text
https://www.googleapis.com/auth/cloud-platform
```
### Vault Identity Features
### Required Permissions
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.
The credentials given to Vault must have the following roles:
#### Group Aliases
```text
roles/iam.serviceAccountKeyAdmin
roles/browser
```
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:
Note that this is the permission **given to the Vault servers**. The IAM
service account or GCE instance that is authenticating _against_ Vault must
have the following role:
```javascript
```text
roles/iam.serviceAccountTokenCreator
```
## Group Aliases
As of Vault 1.0, roles can specify an `add_group_aliases` boolean parameter
that adds [group aliases][identity-group-aliases] to the auth response. These
aliases can aid in building reusable policies since they are available as
interpolated values in Vault's policy engine. Once enabled, the auth response
will include the following aliases:
```json
[
"project-$PROJECT_ID",
"folder-$SUBFOLDER_ID",
"folder-$FOLDER_ID",
"organization-$ORG_ID"
"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
## Implementation Details
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 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:
@ -253,7 +205,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
@ -274,14 +226,20 @@ 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.
### Generating IAM JWT
## Generating JWTs
This section details the various methods and examples for obtaining JWT
tokens.
### IAM
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.
#### curl
#### curl Example
Vault requires the following minimum claim set:
@ -307,12 +265,13 @@ ROLE="my-role"
PROJECT="my-project"
SERVICE_ACCOUNT="service-account@my-project.iam.gserviceaccount.com"
OAUTH_TOKEN="$(oauth2l header cloud-platform)"
JWT_CLAIM="{\\\"aud\\\":\\\"vault/${ROLE}\\\", \\\"sub\\\": \\\"${SERVICE_ACCOUNT}\\\"}"
curl \
--header "${OAUTH_TOKEN}" \
--header "Content-Type: application/json" \
--request POST \
--data "{\"aud\":\"vault/${ROLE}\", \"sub\": \"${SERVICE_ACCOUNT}\"}" \
--data "{\"payload\": \"${JWT_CLAIM}\"}" \
"https://iam.googleapis.com/v1/projects/${PROJECT}/serviceAccounts/${SERVICE_ACCOUNT}:signJwt"
```
@ -331,11 +290,13 @@ $ gcloud beta iam service-accounts sign-jwt $INPUT_JWT_CLAIMS $OUTPUT_JWT_FILE \
Read more on the
[Google Open Source blog](https://opensource.googleblog.com/2017/08/hashicorp-vault-and-google-cloud-iam.html).
### Generating GCE Tokens
### GCE
GCE tokens can only be generated from a GCE instance. **You must run these
commands from the GCE instance.** The JWT token can be obtained from the
`service-accounts/default/identity` endpoint for a instance's metadata server.
GCE tokens **can only be generated from a GCE instance**. The JWT token can be
obtained from the `service-accounts/default/identity` endpoint for a
instance's metadata server.
#### curl Example
```text
ROLE="my-gce-role"
@ -360,3 +321,4 @@ The GCP Auth Plugin has a full HTTP API. Please see the
[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
[repo]: https://github.com/hashicorp/vault-plugin-auth-gcp

3
website/source/docs/secrets/gcp/index.html.md
View File

@ -139,7 +139,7 @@ to GCP APIs:
```sh
$ curl -H "Authorization: Bearer ya29.c.ElodBmNPwHUNY5gcBpnXcE4ywG4w1k..."
```
```
### Service Account Keys
@ -288,7 +288,6 @@ minimum scope(s):
```text
https://www.googleapis.com/auth/cloud-platform
https://www.googleapis.com/auth/iam
```
### Required Permissions

27
website/source/docs/secrets/gcpkms/index.html.md
View File

@ -353,7 +353,7 @@ on [Google Compute Engine][gce] or [Google Kubernetes Engine][gke]
For more information on service accounts, please see the [Google Cloud Service
Accounts documentation][service-accounts].
To use this storage backend, the service account must have the following
To use this secrets engine, the service account must have the following
minimum scope(s):
```text
@ -362,28 +362,7 @@ https://www.googleapis.com/auth/kms
### Required Permissions
The credentials given to Vault must have the following permissions:
```text
locations.keyRings.create
locations.keyRings.cryptoKeys.list
locations.keyRings.cryptoKeys.get
locations.keyRings.cryptoKeys.create
locations.keyRings.cryptoKeys.encrypt
locations.keyRings.cryptoKeys.decrypt
locations.keyRings.cryptoKeys.patch
locations.keyRings.cryptoKeys.updatePrimaryVersion
locations.keyRings.cryptoKeys.cryptoKeyVersions.list
locations.keyRings.cryptoKeys.cryptoKeyVersions.get
locations.keyRings.cryptoKeys.cryptoKeyVersions.create
locations.keyRings.cryptoKeys.cryptoKeyVersions.patch
locations.keyRings.cryptoKeys.cryptoKeyVersions.destroy
locations.keyRings.cryptoKeys.cryptoKeyVersions.asymmetricDecrypt
locations.keyRings.cryptoKeys.cryptoKeyVersions.asymmetricSign
locations.keyRings.cryptoKeys.cryptoKeyVersions.getPublicKey
```
For simplicity, you can use this role instead:
The credentials given to Vault must have the following role:
```text
roles/cloudkms.admin
@ -403,7 +382,7 @@ To sign and verify, you only need the following permissions:
roles/cloudkms.signerVerifier
```
For more information, please see the [Google Cloud KMS IAM documentation][kms-iam]
For more information, please see the [Google Cloud KMS IAM documentation][kms-iam].
## FAQ