GCP IAM

The gcp-iam lease backend calls the IAM Credentials API to generate a short-lived OAuth2 access token by impersonating a service account.

Configuration

[leases.gcp]
type = "gcp-iam"
service_account_email = "my-sa@my-project.iam.gserviceaccount.com"
duration = "1h"

Field	Required	Description
service_account_email	Yes	Service account to impersonate
scopes	No	OAuth2 scopes (default: ["https://www.googleapis.com/auth/cloud-platform"])
env_var	No	Environment variable name for the token (default: CLOUDSDK_AUTH_ACCESS_TOKEN)
duration	No	Lease duration (e.g., "1h", "30m")

Prerequisites

The backend needs GCP credentials to call the IAM Credentials API. fnox looks for them in this order:

1. GOOGLE_APPLICATION_CREDENTIALS environment variable (path to service account JSON)
2. GCP_SERVICE_ACCOUNT_KEY environment variable
3. ~/.config/gcloud/application_default_credentials.json (from gcloud auth application-default login)

If none are found, fnox prints:

GCP credentials not found. Run 'gcloud auth application-default login' or set GOOGLE_APPLICATION_CREDENTIALS.

Credentials Produced

Environment Variable	Description
CLOUDSDK_AUTH_ACCESS_TOKEN	OAuth2 access token

The default CLOUDSDK_AUTH_ACCESS_TOKEN is read by the gcloud CLI. GCP client libraries (Python, Java, Go, Node.js) typically read GOOGLE_OAUTH_ACCESS_TOKEN instead. Set env_var to match your target tool:

# For GCP SDKs (not gcloud CLI):
env_var = "GOOGLE_OAUTH_ACCESS_TOKEN"

Limits

• Max duration: 1 hour (can be extended to 12h with an org policy)
• Revocation: No-op — tokens expire automatically

IAM Setup

The calling identity needs the Service Account Token Creator role on the target service account:

gcloud iam service-accounts add-iam-policy-binding \
  my-sa@my-project.iam.gserviceaccount.com \
  --member="user:you@example.com" \
  --role="roles/iam.serviceAccountTokenCreator"

The IAM Credentials API must be enabled:

gcloud services enable iamcredentials.googleapis.com --project=my-project

Examples

With stored credentials

[providers.op]
type = "1password"
vault = "Development"

[secrets]
GOOGLE_APPLICATION_CREDENTIALS = { provider = "op", value = "GCP SA/key file", as_file = true }

[leases.gcp]
type = "gcp-iam"
service_account_email = "my-sa@my-project.iam.gserviceaccount.com"
duration = "1h"

fnox exec -- gcloud storage ls

With gcloud login

gcloud auth application-default login

# fnox picks up ADC automatically
fnox exec -- gcloud storage ls

Custom scopes

[leases.gcp]
type = "gcp-iam"
service_account_email = "my-sa@my-project.iam.gserviceaccount.com"
scopes = [
  "https://www.googleapis.com/auth/cloud-platform",
  "https://www.googleapis.com/auth/bigquery"
]

See Also

• Credential Leases — overview and approaches
• GCP Secret Manager provider — for storing secrets in GCP