Skip to content

GCP Secret Manager

Secret Agent can authenticate with GCP Secret Manager using the following methods:

Attached service account

This is the recommended way to authenticate with GCP because it does not require any credentials in the Secret Agent configuration file. When Secret Agent runs on a GCP VM with a service account attached, it automatically uses the credentials of that service account. The attached service account must have the Secret Manager Secret Accessor role.

To configure Secret Agent on a GCP VM with an attached service account:

  1. Create a secret in GCP Secret Manager. In this example, the secret is named TestingSecret.
  2. Create a service account with the Secret Manager Secret Accessor role. In this example, the service account is named test-service-account@xxx.iam.gserviceaccount.com.
  3. Create a VM with the test-service-account@xxx.iam.gserviceaccount.com service account attached. From the GCP console:
    1. Click Create Instance in VM Instances under Compute Engine.
    2. Go to Identity and API access.
    3. Select test-service-account@xxx.iam.gserviceaccount.com in Service account.
  4. Install Secret Agent on the GCP VM.
  5. Configure Secret Agent to fetch secrets from GCP Secret Manager.
  6. Start Secret Agent.

Sample configuration file:

service:
  tcp:
    endpoint: 0.0.0.0:3005


secret-manager:
  gcp:
    resources:
      TestRes: projects/xxxxxxxxxxxx/secrets/TestingSecret/versions/latest


log:
  level: info

Application Default Credentials

Application Default Credentials (ADC) is a strategy that the Google Cloud client libraries use to automatically find credentials based on the application environment. With ADC, you can provide credentials to Secret Agent by setting an environment variable, placing a credentials file on disk, or specifying a credential file path directly in the Secret Agent configuration.

Use ADC when Secret Agent runs outside of GCP (for example, on-premises or in another cloud provider), when the GCP VM does not have a service account attached, or when you need to authenticate with a different service account from the one attached to the VM.

Secret Agent looks for Application Default Credentials in the following order:

  1. Secret Agent configuration file.
  2. The environment variable GOOGLE_APPLICATION_CREDENTIALS.
  3. The default credentials file ~/.config/gcloud/application_default_credentials.json.
  4. GCP VM attached service account credentials.

To configure Secret Agent with Application Default Credentials:

  1. Create a service account with the Secret Manager Secret Accessor role. In this example, the service account is named test-service-account@xxx.iam.gserviceaccount.com.
  2. Create a secret in GCP Secret Manager. In this example, the secret is named TestingSecret.
  3. Download the key file in JSON format for the test-service-account@xxx.iam.gserviceaccount.com service account.
  4. Install Secret Agent on the machine.
  5. Configure Secret Agent and set the credential-file parameter to the path of the downloaded service account credential file.
  6. Start Secret Agent.

Sample configuration file:

service:
  tcp:
    endpoint: 0.0.0.0:3005


secret-manager:
  gcp:
    resources:
      TestRes: projects/xxxxxxxxxxxx/secrets/TestingSecret/versions/latest
    credential-file: PATH_TO_SERVICE_ACCOUNT_CREDENTIAL_FILE


log:
  level: info

Service account impersonation

You can use service account impersonation with either of the preceding authentication methods (attached service account and Application Default Credentials). With impersonation, you start with an authenticated principal (your Google Account or a service account) and request short-lived credentials for a service account that has authorization to access secrets. The authenticated principal must have permission to impersonate the target service account.

Service account impersonation is more secure than using a service account key because it requires a prior authenticated identity, and the credentials created through impersonation do not persist. By comparison, authenticating with a service account key requires no prior authentication, and the persistent key is a high-risk credential if exposed.

To configure Secret Agent with service account impersonation:

  1. Create a secret in GCP Secret Manager. In this example, the secret is named TestingSecret.
  2. Create a service account with the Service Account Token Creator role. In this example, this service account is named base-service-account@xxx.iam.gserviceaccount.com.
  3. Create a service account with the Secret Manager Secret Accessor role. In this example, this service account is named test-service-account@xxx.iam.gserviceaccount.com.
  4. Verify that the IAM Service Account Credentials API is enabled for your GCP project.
  5. Create a GCP VM with base-service-account@xxx.iam.gserviceaccount.com attached. From the GCP console:
    1. Click Create Instance in VM Instances under Compute Engine.
    2. Go to Identity and API access.
    3. Select base-service-account@xxx.iam.gserviceaccount.com in Service account.
  6. Install Secret Agent on the GCP VM.
  7. Configure Secret Agent to fetch secrets from GCP Secret Manager. Set impersonate to test-service-account@xxx.iam.gserviceaccount.com in the configuration file. This service account has permission to access secrets.
  8. Start Secret Agent.

Sample configuration file:

service:
  tcp:
    endpoint: 0.0.0.0:3005


secret-manager:
  gcp:
    resources:
      TestRes: projects/xxxxxxxxxxxx/secrets/TestingSecret/versions/latest
    credential-file: PATH_TO_BASE_SERVICE_ACCOUNT_CREDENTIAL_FILE
    impersonate: test-service-account@xxx.iam.gserviceaccount.com


log:
  level: info

Accessing secrets across projects

You can access secrets across GCP projects using the same service account credentials.

  1. Create a service account with the Secret Manager Secret Accessor role in Project1. In this example, the service account is named test-service-account-project1@xxx.iam.gserviceaccount.com.
  2. Create a secret in another GCP project (Project2). In this example, the secret is named TestingSecretProject2.
  3. Download the key file in JSON format for test-service-account-project1@xxx.iam.gserviceaccount.com.
  4. Grant test-service-account-project1@xxx.iam.gserviceaccount.com the Secret Manager Secret Accessor role in Project2. From the GCP console:
    1. Select Project2 from the project list.
    2. Go to Grant Access in IAM.
    3. Add test-service-account-project1@xxx.iam.gserviceaccount.com as a principal and assign the Secret Manager Secret Accessor role.
  5. Install Secret Agent on the machine.
  6. Configure Secret Agent and set the credential-file parameter to the path of the downloaded service account credential file.
  7. Start Secret Agent.

Sample configuration file for cross-project access:

service:
  tcp:
    endpoint: 0.0.0.0:3005


secret-manager:
  gcp:
    resources:
      TestResProj2: projects/yyyyyyyyyyyy/secrets/TestingSecretProject2/versions/latest
    credential-file: PATH_TO_SERVICE_ACCOUNT_CREDENTIAL_FILE


log:
  level: info

Accessing multiple versions of a secret

Secrets in GCP Secret Manager can have multiple versions. To access specific versions, define each as a separate resource in the configuration file:

service:
  tcp:
    endpoint: 0.0.0.0:3005


secret-manager:
  gcp:
    resources:
      TestResV1: projects/yyyyyyyyyyyy/secrets/TestingSecret/versions/1
      TestResV2: projects/yyyyyyyyyyyy/secrets/TestingSecret/versions/2
      TestResLatest: projects/yyyyyyyyyyyy/secrets/TestingSecret/versions/latest


log:
  level: info
Feedback

Was this page helpful?

What type of feedback are you giving?

What would you like us to know?

+Capture screenshot

Can we reach out to you?