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:
Google Cloud IAM service accounts
Google Compute Engine (GCE) instances
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,
but is automatically bundled in Vault releases. Please file all feature
requests, bugs, and pull requests specific to the GCP plugin under that
repository.
For more usage information, run vault auth help gcp.
Note: The project parameter has been removed in Vault 1.5.9+, 1.6.5+, and 1.7.2+.
It is no longer needed for configuration and will be ignored if provided.
Auth methods must be configured in advance before users or machines can
authenticate. These steps are usually completed by an operator or configuration
management tool.
If you are using instance credentials or want to specify credentials via
an environment variable, you can skip this step. To learn more, see the
Google Cloud Authentication section below.
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
Cloud.
The environment variable GOOGLE_APPLICATION_CREDENTIALS. This is specified
as the path to a Google Cloud credentials file, typically for a service
account. If this environment variable is present, the resulting credentials are
used. If the credentials are invalid, an error is returned.
Default instance credentials. When no environment variable is present, the
default service account credentials are used.
Note that the previously mentioned permissions are given to the Vault servers.
The IAM service account or GCE instance that is authenticating against Vault
must have the following role:
roles/iam.serviceAccountTokenCreator
roles/iam.serviceAccountTokenCreator
WARNING: Make sure this role is only applied so your service account can
impersonate itself. If this role is applied GCP project-wide, this will allow the service
account to impersonate any service account in the GCP project where it resides.
See Managing service account impersonation
for more information.
As of Vault 1.0, roles can specify an add_group_aliases boolean parameter
that adds 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:
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.
The client sends this signed JWT to Vault along with a role name.
Vault extracts the kid header value, which contains the ID of the
key-pair used to generate the JWT, and the sub ID/email to find the service
account key. If the service account does not exist or the key is not linked to
the service account, Vault denies authentication.
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 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
another cloud provider.
The client sends this JWT to Vault along with a role name.
Vault extracts the kid header value, which contains the ID of the
key-pair used to generate the JWT, to find the OAuth2 public cert to verify
this JWT.
Vault authorizes the confirmed instance against the given role, ensuring
the instance matches the bound zones, regions, or instance groups. If that is
successful, a Vault token with the proper policies is returned.
This describes how to use the GCP Service Account Credentials API 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.
For the API method, providing the expiration claim exp is required. If it is omitted,
it will not be added automatically and Vault will deny authentication. Expiration must
be specified as a NumericDate 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.
One you have all this information, the JWT token can be signed using curl and
oauth2l:
You can also do this through the (currently beta) gcloud command. Note that you will
be required to provide the expiration claim exp as a part of the JWT input to the
command.
$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
$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
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.
The following code snippet demonstrates the Google Cloud auth method to authenticate
with Vault.
gcp auth example
gcp auth example
Go
Go
package main
import("context""encoding/json""fmt""os""time"
credentials "cloud.google.com/go/iam/credentials/apiv1"
vault "github.com/hashicorp/vault/api"
credentialspb "google.golang.org/genproto/googleapis/iam/credentials/v1")// Fetches a key-value secret (kv-v2) after authenticating to Vault via GCP IAM,// one of two auth methods used to authenticate with GCP (the other is GCE auth).//// A role must first be created in Vault bound to the IAM user's service account you wish to authenticate with, like so:// vault write auth/gcp/role/dev-role-iam \// type="iam" \// policies="dev-policy" \// bound_service_accounts="my-service@my-project.iam.gserviceaccount.com"// Your Vault instance must also be configured with GCP credentials to perform API calls to IAM, like so:// vault write auth/gcp/config credentials=@path/to/server/creds.json// Learn more at https://www.vaultproject.io/docs/auth/gcpfuncgetSecretWithGCPAuthIAM()(string,error){
config := vault.DefaultConfig()// modify for more granular configuration
client, err := vault.NewClient(config)if err !=nil{return"", fmt.Errorf("unable to initialize Vault client: %w", err)}// Learn about authenticating to GCS with service account credentials at https://cloud.google.com/docs/authentication/productionif pathToCreds := os.Getenv("GOOGLE_APPLICATION_CREDENTIALS"); pathToCreds ==""{
fmt.Printf("WARNING: Environment variable GOOGLE_APPLICATION_CREDENTIALS was not set. IAM client for JWT signing and Vault server IAM client will both fall back to default instance credentials.\n")}
jwtResp, err :=signJWT()if err !=nil{return"", fmt.Errorf("unable to sign JWT for authenticating to GCP: %w", err)}// send login request to Vault with signed JWT token
params :=map[string]interface{}{"role":"dev-role-iam",// the name of the role in Vault that was created with this IAM bound to it"jwt": jwtResp.SignedJwt,}// Environment variable GOOGLE_APPLICATION_CREDENTIALS pointing to the path to a valid credentials JSON must be set,// or Vault will fall back to Google's default instance credentials
resp, err := client.Logical().Write("auth/gcp/login", params)if err !=nil{return"", fmt.Errorf("unable to log in with GCP IAM auth: %w", err)}
client.SetToken(resp.Auth.ClientToken)
secret, err := client.Logical().Read("kv-v2/data/creds")if err !=nil{return"", fmt.Errorf("unable to read secret: %w", err)}
data, ok := secret.Data["data"].(map[string]interface{})if!ok {return"", fmt.Errorf("data type assertion failed: %T %#v", secret.Data["data"], secret.Data["data"])}// data map can contain more than one key-value pair, in this case we're just grabbing one of them
key :="password"
value, ok := data[key].(string)if!ok {return"", fmt.Errorf("value type assertion failed: %T %#v", data[key], data[key])}return value,nil}// generate signed JWT token from GCP IAMfuncsignJWT()(*credentialspb.SignJwtResponse,error){
svcAccountEmail := fmt.Sprintf("%s@%s.iam.gserviceaccount.com", os.Getenv("GCP_SERVICE_ACCOUNT_NAME"), os.Getenv("GOOGLE_CLOUD_PROJECT"))
ctx := context.Background()
iamClient, err := credentials.NewIamCredentialsClient(ctx)// can pass option.WithCredentialsFile("path/to/creds.json") as second param if GOOGLE_APPLICATION_CREDENTIALS env var not setif err !=nil{returnnil, fmt.Errorf("unable to initialize IAM credentials client: %w", err)}defer iamClient.Close()
resourceName := fmt.Sprintf("projects/-/serviceAccounts/%s", svcAccountEmail)
jwtPayload :=map[string]interface{}{"aud":"vault/dev-role-iam",// the name of the role in Vault that was created with this IAM service account bound to it"sub": svcAccountEmail,"exp": time.Now().Add(time.Minute *10).Unix(),}
payloadBytes, err := json.Marshal(jwtPayload)if err !=nil{returnnil, fmt.Errorf("unable to marshal jwt payload to json: %w", err)}
signJWTReq :=&credentialspb.SignJwtRequest{
Name: resourceName,
Payload:string(payloadBytes),}
jwtResp, err := iamClient.SignJwt(ctx, signJWTReq)if err !=nil{returnnil, fmt.Errorf("unable to sign JWT: %w", err)}return jwtResp,nil}
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100101102103104105106107108109110111112113package mainimport("context""encoding/json""fmt""os""time" credentials "cloud.google.com/go/iam/credentials/apiv1" vault "github.com/hashicorp/vault/api" credentialspb "google.golang.org/genproto/googleapis/iam/credentials/v1")// Fetches a key-value secret (kv-v2) after authenticating to Vault via GCP IAM,// one of two auth methods used to authenticate with GCP (the other is GCE auth).//// A role must first be created in Vault bound to the IAM user's service account you wish to authenticate with, like so:// vault write auth/gcp/role/dev-role-iam \// type="iam" \// policies="dev-policy" \// bound_service_accounts="my-service@my-project.iam.gserviceaccount.com"// Your Vault instance must also be configured with GCP credentials to perform API calls to IAM, like so:// vault write auth/gcp/config credentials=@path/to/server/creds.json// Learn more at https://www.vaultproject.io/docs/auth/gcpfuncgetSecretWithGCPAuthIAM()(string,error){ config := vault.DefaultConfig()// modify for more granular configuration client, err := vault.NewClient(config)if err !=nil{return"", fmt.Errorf("unable to initialize Vault client: %w", err)}// Learn about authenticating to GCS with service account credentials at https://cloud.google.com/docs/authentication/productionif pathToCreds := os.Getenv("GOOGLE_APPLICATION_CREDENTIALS"); pathToCreds ==""{ fmt.Printf("WARNING: Environment variable GOOGLE_APPLICATION_CREDENTIALS was not set. IAM client for JWT signing and Vault server IAM client will both fall back to default instance credentials.\n")} jwtResp, err :=signJWT()if err !=nil{return"", fmt.Errorf("unable to sign JWT for authenticating to GCP: %w", err)}// send login request to Vault with signed JWT token params :=map[string]interface{}{"role":"dev-role-iam",// the name of the role in Vault that was created with this IAM bound to it"jwt": jwtResp.SignedJwt,}// Environment variable GOOGLE_APPLICATION_CREDENTIALS pointing to the path to a valid credentials JSON must be set,// or Vault will fall back to Google's default instance credentials resp, err := client.Logical().Write("auth/gcp/login", params)if err !=nil{return"", fmt.Errorf("unable to log in with GCP IAM auth: %w", err)} client.SetToken(resp.Auth.ClientToken) secret, err := client.Logical().Read("kv-v2/data/creds")if err !=nil{return"", fmt.Errorf("unable to read secret: %w", err)} data, ok := secret.Data["data"].(map[string]interface{})if!ok {return"", fmt.Errorf("data type assertion failed: %T %#v", secret.Data["data"], secret.Data["data"])}// data map can contain more than one key-value pair, in this case we're just grabbing one of them key :="password" value, ok := data[key].(string)if!ok {return"", fmt.Errorf("value type assertion failed: %T %#v", data[key], data[key])}return value,nil}// generate signed JWT token from GCP IAMfuncsignJWT()(*credentialspb.SignJwtResponse,error){ svcAccountEmail := fmt.Sprintf("%s@%s.iam.gserviceaccount.com", os.Getenv("GCP_SERVICE_ACCOUNT_NAME"), os.Getenv("GOOGLE_CLOUD_PROJECT")) ctx := context.Background() iamClient, err := credentials.NewIamCredentialsClient(ctx)// can pass option.WithCredentialsFile("path/to/creds.json") as second param if GOOGLE_APPLICATION_CREDENTIALS env var not setif err !=nil{returnnil, fmt.Errorf("unable to initialize IAM credentials client: %w", err)}defer iamClient.Close() resourceName := fmt.Sprintf("projects/-/serviceAccounts/%s", svcAccountEmail) jwtPayload :=map[string]interface{}{"aud":"vault/dev-role-iam",// the name of the role in Vault that was created with this IAM service account bound to it"sub": svcAccountEmail,"exp": time.Now().Add(time.Minute *10).Unix(),} payloadBytes, err := json.Marshal(jwtPayload)if err !=nil{returnnil, fmt.Errorf("unable to marshal jwt payload to json: %w", err)} signJWTReq :=&credentialspb.SignJwtRequest{ Name: resourceName, Payload:string(payloadBytes),} jwtResp, err := iamClient.SignJwt(ctx, signJWTReq)if err !=nil{returnnil, fmt.Errorf("unable to sign JWT: %w", err)}return jwtResp,nil}
