Google Cloud Platform Identity Provider

The GCP Identity Provider allows users to seamlessly use SecretHub with any application running on GCP. By using the Identity Provider, service accounts can be created that do not have a key that has to be copied anywhere. Instead, the integration leverages GCP native services (KMS and IAM) to handle encryption and authentication.

The integration supports the following GCP services:

General schematic overview of SecretHub GCP integration functionality

Service Accounts

Any application running on GCP needs its own SecretHub Service Account for GCP. These service accounts have two prerequisites:

  • A KMS key that is used for encryption of the account. KMS keys can be reused for multiple service accounts.
  • A GCP Service Account that is used by the service that is running the application. This service account must have decryption rights on the KMS key. Because the GCP Service Account is used for identifying the service account, each GCP Service Account can be used for at most one SecretHub service account.

Creating SecretHub Service Accounts

To create a SecretHub Service Account for GCP, you need to take the following steps:

  1. Create KMS key: use the gcloud CLI, GCP Console or any other method to create a symmetric encryption key on GCP.
  2. Create GCP Service Account: use the gcloud CLI, GCP Console or any other method to create a GCP Service Account. This service account must be granted the cloudkms.cryptoKeyVersions.useToDecrypt permission on the previously created KMS key.
  3. Create a SecretHub Service Account for GCP: use SecretHub CLI, Go SDK or Terraform Provider to create a service account on SecretHub.

The diagram below illustrates the process of creating a service account:

Overview of creating a SecretHub GCP service


To create a SecretHub service account for GCP through the CLI, the following command can be used:

secrethub service gcp init <namespace>/<repo> \
    --kms-key <kms-key> \
    --service-account-email <service-account-email> \

For further details, see the command reference docs for secrethub service gcp, which also contains all other commands related to service accounts for GCP.

Golang SDK

Service accounts for GCP can also be created using the Golang SDK. You can find further details as well as an example on how to do this in the GoDoc.

Linking GCP Projects

When creating a SecretHub service account for a GCP Project that has not previously been used in the SecretHub namespace, you will be asked by the CLI to link the GCP Project to the SecretHub namespace. In this process, you will be asked to login to GCP in your browser and grant SecretHub the iam.test permission. This is a very restrictive permission, used to verify that you have access to the GCP Project.

Once this test has been performed, the SecretHub API will automatically revoke all its access to your account. This can be verified by going to Google’s Third Party Access Overview; any listing of SecretHub should be gone in a minute. If, for some reason, SecretHub is still listed after a few minutes, you can safely click REMOVE ACCESS.

Since the SecretHub CLI automatically detects missing links, normally there is no need to manually manage them. Nevertheless, these commands can be used to add, list and delete links:

Using SecretHub Service Accounts

Using SecretHub with the GCP Identity Provider is really simple. As long as your workload (GCE Instance, GKE Container, etc) uses the GCP Service Account attached to the SecretHub service account, it can automatically fetch and decrypt the secrets it needs.

When you invoke SecretHub with the GCP Identity Provider enabled, the integration automatically communicates with the necessary GCP services to provide authentication and decryption.

How this works is demonstrated in the following diagram:

Overview of using the SecretHub GCP Identity Provider

The Identity Provider can be invoked in multiple ways, depending on how you use SecretHub.


For the CLI there are two different options for invoking the GCP Identity Provider:

  • Use the --identity-provider=gcp flag for the CLI.
  • Set the SECRETHUB_IDENTITY_PROVIDER environment variable to gcp.

Golang SDK

By setting the SECRETHUB_IDENTITY_PROVIDER environment variable to gcp, you can initialize the client for the Golang SDK using secrethub.NewClient(). The client then automatically sets up the Identity Provider for GCP.

It is also possible to explicitly initialize the client with the GCP Identity Provider:

import (

func main() {
    creds := credentials.UseGCPServiceAccount()
    client, err := secrethub.NewClient(secrethub.WithCredentials(creds))

The client will automatically use the native GCP services for authentication and decryption instead of the default credential key file.

Google Kubernetes Engine

To use the GCP Idenitty Provider with Google Kubernetes Engine, Workload Identity has to be enabled. This either means that the GKE cluster has to be created with the Workload Identity option enabled or the option has to be enabled for an existing custer.

Once Workload Identity is enabled, you can authorize a Kubernetes Service Account to act as a GCP Service Account. To achieve this, you first have to create a IAM policy binding for the GCP Service Account:

gcloud iam service-accounts add-iam-policy-binding \
  --role roles/iam.workloadIdentityUser \
  --member "[k8s_namespace/ksa_name]" \

Where the following values should be replaced:

  • project-id is the ID of the GCP project where the GKE Cluster is in.
  • k8s_namespace/ksa_name are the namespace and name of the Kubernetes Service Account.
  • gsa_name is the name of the GCP Service Account.
  • gsa_project is the ID of GCP Project the GCP Service Account is in.

The Kubernetes Service Account also needs a reference to the GCP Service Account in the form of an annotation:

kubectl annotate serviceaccount \
  --namespace k8s_namespace \
   ksa_name \

If the binding between a Kubernetes and GCP Service Account is made both ways, you can create a SecretHub Service Account for the GCP Service Account. Then use the Kubernetes Service Account for your workload to access SecretHub:

apiVersion: v1
kind: Pod
  name: my-pod
  serviceAccountName: ksa_name
    - name: my-container
      image: secrethub/demo-app
          value: gcp
        - name: MY_SECRET
          value: secrethub://path/to/secret

For a complete example, check the GKE Guide.

See also