GCP OIDC Integration

Available on the Enterprise plan. Contact sales to learn more.

Ona environments can access Google Cloud resources using Workload Identity Federation. You create a workload identity pool with an OIDC provider that trusts Ona’s tokens, then grant the federated identity access to GCP resources. No service account keys are needed.

Prerequisites

Enable V3 tokens on the OIDC Token Configuration page in your organization settings. See Enable V3 tokens.
Google Cloud CLI (gcloud) installed in your environment.

How it works

Ona issues a JWT with claims about the environment, user, and organization.
The environment sends the JWT to Google’s Security Token Service (STS).
STS validates the token against Ona’s OIDC discovery endpoint and returns a federated access token.
The environment uses the federated token to access GCP resources directly, or impersonates a service account for broader access.

Step 1: Create a workload identity pool

Create a workload identity pool to manage Ona’s federated identities:

gcloud iam workload-identity-pools create ona-pool \
  --location="global" \
  --display-name="Ona Environments" \
  --project=<PROJECT_ID>

Step 2: Create an OIDC provider

Add an OIDC provider to the pool that trusts Ona’s tokens:

gcloud iam workload-identity-pools providers create-oidc ona-provider \
  --location="global" \
  --workload-identity-pool="ona-pool" \
  --issuer-uri="https://app.gitpod.io" \
  --allowed-audiences="https://iam.googleapis.com/projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/ona-pool/providers/ona-provider" \
  --attribute-mapping="google.subject=assertion.sub,attribute.organization_id=assertion.organization_id,attribute.environment_id=assertion.environment_id,attribute.project_id=assertion.project_id" \
  --attribute-condition="assertion.organization_id == '<ONA_ORG_ID>'" \
  --project=<PROJECT_ID>

Key parameters:

Parameter	Description
`--issuer-uri`	`https://app.gitpod.io`
`--allowed-audiences`	The full provider resource name (used as the `--audience` in `ona idp token`)
`--attribute-mapping`	Maps Ona token claims to GCP attributes
`--attribute-condition`	CEL expression that restricts which tokens are accepted

Attribute mappings

Attribute mappings define how Ona token claims map to GCP identity attributes. google.subject is required. Additional custom attributes enable fine-grained IAM bindings. Common mappings for V3 tokens:

google.subject=assertion.sub
attribute.organization_id=assertion.organization_id
attribute.environment_id=assertion.environment_id
attribute.project_id=assertion.project_id
attribute.creator_email=assertion.creator_email
attribute.email=assertion.email

Attribute conditions

Attribute conditions restrict which tokens the provider accepts. Use CEL expressions to filter on Ona claims. Allow only a specific Ona organization:

assertion.organization_id == '<ONA_ORG_ID>'

Allow only a specific project:

assertion.organization_id == '<ONA_ORG_ID>' && assertion.project_id == '<ONA_PROJECT_ID>'

Allow only environments created by a specific user:

assertion.organization_id == '<ONA_ORG_ID>' && assertion.creator_email == 'dev@example.com'

Always set an attribute condition. Without one, any valid Ona token from any organization can authenticate to your pool.

Step 3: Grant access to GCP resources

You can grant access using direct resource bindings or service account impersonation.

Option A: Direct resource access

Grant the federated identity access directly on a GCP resource:

# Allow all identities in the pool
gcloud storage buckets add-iam-policy-binding gs://<BUCKET_NAME> \
  --member="principalSet://iam.googleapis.com/projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/ona-pool/*" \
  --role="roles/storage.objectViewer"

To restrict to a specific Ona project, use the attribute.project_id attribute:

gcloud storage buckets add-iam-policy-binding gs://<BUCKET_NAME> \
  --member="principalSet://iam.googleapis.com/projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/ona-pool/attribute.project_id/<ONA_PROJECT_ID>" \
  --role="roles/storage.objectViewer"

To restrict to a single identity (specific sub claim):

gcloud storage buckets add-iam-policy-binding gs://<BUCKET_NAME> \
  --member="principal://iam.googleapis.com/projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/ona-pool/subject/organization_id:<ONA_ORG_ID>:project_id:<ONA_PROJECT_ID>" \
  --role="roles/storage.objectViewer"

Option B: Service account impersonation

If the GCP APIs you need do not support direct Workload Identity Federation, impersonate a service account instead.

Create a service account:

gcloud iam service-accounts create ona-sa \
  --display-name="Ona Environment SA" \
  --project=<PROJECT_ID>

Grant the federated identity permission to impersonate the service account:

gcloud iam service-accounts add-iam-policy-binding ona-sa@<PROJECT_ID>.iam.gserviceaccount.com \
  --member="principalSet://iam.googleapis.com/projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/ona-pool/attribute.organization_id/<ONA_ORG_ID>" \
  --role="roles/iam.workloadIdentityUser"

Grant the service account access to the resources it needs:

gcloud projects add-iam-policy-binding <PROJECT_ID> \
  --member="serviceAccount:ona-sa@<PROJECT_ID>.iam.gserviceaccount.com" \
  --role="roles/storage.objectViewer"

Step 4: Authenticate from an environment

Create a credential configuration file

Create a credential configuration file that tells the GCP SDK how to obtain tokens from Ona:

gcloud iam workload-identity-pools create-cred-config \
  projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/ona-pool/providers/ona-provider \
  --output-file=gcp-credentials.json \
  --executable-command="ona idp token --audience https://iam.googleapis.com/projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/ona-pool/providers/ona-provider" \
  --executable-timeout-millis=5000

For service account impersonation, add the --service-account flag:

gcloud iam workload-identity-pools create-cred-config \
  projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/ona-pool/providers/ona-provider \
  --service-account=ona-sa@<PROJECT_ID>.iam.gserviceaccount.com \
  --output-file=gcp-credentials.json \
  --executable-command="ona idp token --audience https://iam.googleapis.com/projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/ona-pool/providers/ona-provider" \
  --executable-timeout-millis=5000

Authenticate

Set the GOOGLE_APPLICATION_CREDENTIALS environment variable and enable executable-based credentials:

export GOOGLE_APPLICATION_CREDENTIALS=$(pwd)/gcp-credentials.json
export GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES=1

Then use GCP tools normally:

gcloud auth login --cred-file=gcp-credentials.json
gcloud storage ls gs://my-bucket

Automate on environment startup

Add the credential setup to your automations:

# automations.yaml
tasks:
  gcp-login:
    name: GCP Login
    command: |
      export GOOGLE_APPLICATION_CREDENTIALS=/workspace/gcp-credentials.json
      export GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES=1
      gcloud auth login --cred-file=$GOOGLE_APPLICATION_CREDENTIALS
    triggeredBy:
      - postDevcontainerStart

Store the credential configuration file in your repository or generate it during environment startup. It does not contain secrets, only the configuration for how to obtain tokens.

Using V2 tokens with GCP

V2 tokens also work with GCP Workload Identity Federation. The V2 sub claim uses a path-based format (e.g., org:<orgID>/prj:<projectID>/env:<envID>). Adjust your attribute mappings and conditions accordingly. V2 tokens include fewer claims (org, gsub, and standard JWT fields), so attribute mappings are limited to google.subject=assertion.sub and conditions on assertion.sub or assertion.org. See the OIDC overview V2 section for the full V2 sub format reference.

Troubleshooting

"The audience in the credential configuration does not match"

The --audience in ona idp token must match the --allowed-audiences on the OIDC provider. Use the full provider resource name.

"The attribute condition was not met"

Your token’s claims do not satisfy the --attribute-condition CEL expression.
Decode your token: ona idp token --audience <AUDIENCE> --decode
Verify the organization_id, project_id, or other claims match the condition.

"Permission denied on resource"

The federated identity or service account does not have the required IAM role on the target resource.
Check the --member format in your IAM binding. For principalSet://, the attribute value must match exactly.

"Executable returned a non-zero exit code"

The ona idp token command failed. Verify the CLI is installed and authenticated in the environment.
Check that the audience value is correct.

Get Started

Using Ona

Configuration

Administration & Security

Infrastructure

Billing

Learn

Reference

Support

Releases

Prerequisites

How it works

Step 1: Create a workload identity pool

Step 2: Create an OIDC provider

Attribute mappings

Attribute conditions

Step 3: Grant access to GCP resources

Option A: Direct resource access

Option B: Service account impersonation

Step 4: Authenticate from an environment

Create a credential configuration file

Authenticate

Automate on environment startup

Using V2 tokens with GCP

Further reading

Troubleshooting

Get Started

Using Ona

Configuration

Administration & Security

Infrastructure

Billing

Learn

Reference

Support

Releases

Documentation Index

​Prerequisites

​How it works

​Step 1: Create a workload identity pool

​Step 2: Create an OIDC provider

​Attribute mappings

​Attribute conditions

​Step 3: Grant access to GCP resources

​Option A: Direct resource access

​Option B: Service account impersonation

​Step 4: Authenticate from an environment

​Create a credential configuration file

​Authenticate

​Automate on environment startup

​Using V2 tokens with GCP

​Further reading

​Troubleshooting

Prerequisites

How it works

Step 1: Create a workload identity pool

Step 2: Create an OIDC provider

Attribute mappings

Attribute conditions

Step 3: Grant access to GCP resources

Option A: Direct resource access

Option B: Service account impersonation

Step 4: Authenticate from an environment

Create a credential configuration file

Authenticate

Automate on environment startup

Using V2 tokens with GCP

Further reading

Troubleshooting