Authentication and Credentials¶

Authentication is a critical aspect of interacting with Google Cloud Platform services. gcp-pilot simplifies this process by providing several authentication mechanisms and features.

Application Default Credentials (ADC)¶

By default, gcp-pilot uses Application Default Credentials (ADC) to detect credentials. This means that you must have one of the following setups:

Environment variable GOOGLE_APPLICATION_CREDENTIALS pointing to the JSON file with the credentials
Run inside GCP (Compute Engine, Cloud Run, GKE, AppEngine), so the machine's credentials will be used
Run locally after authenticating with gcloud auth application-default login

This approach allows your application to run seamlessly in different environments without code changes.

Service Account Impersonation¶

You can globally set a service account using the environment variable DEFAULT_SERVICE_ACCOUNT, which will require impersonation.

Impersonation allows a service account to act on behalf of another service account. This is useful when you want to: - Use a single service account for authentication but need different permissions for different operations - Avoid distributing service account keys by using impersonation instead

To use impersonation, you need to: 1. Ensure the original service account has the roles/iam.serviceAccountTokenCreator role on the target service account 2. Pass the target service account email to the client using the impersonate_account parameter

from gcp_pilot.storage import CloudStorage

# Impersonate a service account
storage = CloudStorage(impersonate_account="target-sa@project-id.iam.gserviceaccount.com")

Delegation¶

Some services (like Google Workspace) require specific subjects to be delegated. gcp-pilot automatically handles delegation, sometimes even performing additional credential signatures.

To use delegation, you can pass the subject to the client:

from gcp_pilot.directory import Directory

# Use delegation for a specific user
directory = Directory(subject="user@example.com")

Default Project¶

When creating a client, a default project is defined by using the project that the credentials belong to.

Clients that support managing resources from other projects can be overwritten per call.

Example: you create a BigQuery client using credentials from project_a. All calls will query datasets from project_a, unless another project is passed as parameter when performing the call.

You can also globally set a project using the environment variable DEFAULT_PROJECT.

Default Location¶

Similar to the default project, a default location is defined by using the project's location. The project's location will exist if you ever enabled AppEngine, so you had to set a location then. Otherwise, no default location will be set.

You can also globally set a location using the environment variable DEFAULT_LOCATION to reduce the number of API calls when creating clients.

Auto-Authorization¶

Some services require specific authorizations that should be set up prior to their usage, for example: - [Pub/Sub] subscribe to a topic with authenticated push - [Cloud Scheduler] schedule a job to trigger a Cloud Run service - [Cloud Tasks] queue a task to trigger a Cloud Run service

In these cases, gcp-pilot tries its best to ensure that the required permissions are properly set up before the actual request is made.

OIDC Authorization¶

Identity-Aware Proxy (IAP) and other services that require OIDC tokens are automatically handled by gcp-pilot. The library generates the necessary OIDC tokens for services that require authentication.

from gcp_pilot.iap import IdentityAwareProxy

# Generate an OIDC token for a Cloud Run service
iap = IdentityAwareProxy()
token = iap.get_token(url="https://my-service.run.app")