OpenID Connect (OIDC)

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

Ona issues OIDC tokens that environments, users, and service accounts can exchange for short-lived credentials from cloud providers and third-party services. This eliminates static secrets, API keys, and long-lived credentials. OIDC tokens work with both Ona Cloud and self-hosted runners.

Enable V3 tokens

V3 tokens are the current token format. They include flat, structured claims per principal type and a customizable sub claim. To enable V3 tokens for your organization:

Open the OIDC Token Configuration page in your organization settings
Select V3 as the token version
Optionally configure extra sub claim fields
Save

Switching from V2 to V3 changes the sub claim format. Update your cloud provider trust policies before switching. See V2 tokens for the old format.

Token structure

V3 tokens contain flat claims specific to the requesting principal. Every token includes the standard JWT claims (iss, sub, aud, exp, iat) plus principal-specific claims.

Environment tokens

Issued when code running inside an environment requests a token.

{
  "iss": "https://app.gitpod.io",
  "sub": "organization_id:a1b2c3d4-...:project_id:c9d0e1f2-...",
  "aud": ["sts.amazonaws.com"],
  "exp": 1711929600,
  "iat": 1711926000,
  "environment_id": "e5f6a7b8-0000-4000-8000-000000000004",
  "organization_id": "a1b2c3d4-0000-4000-8000-000000000001",
  "project_id": "c9d0e1f2-0000-4000-8000-000000000005",
  "runner_id": "f3a4b5c6-0000-4000-8000-000000000007",
  "creator_principal": "user",
  "creator_id": "b3c4d5e6-0000-4000-8000-000000000003",
  "creator_email": "dev@example.com",
  "creator_name": "Jane Doe",
  "creator_idp": "https://accounts.google.com",
  "creator_idp_claims": { "groups": ["engineering"] },
  "environment_initializers": [
    {
      "git": {
        "remote_uri": "https://github.com/org/repo.git"
      },
      "context_url": "https://github.com/org/repo"
    }
  ]
}

User tokens

Issued when a user requests a token directly (e.g., via the CLI outside an environment).

{
  "iss": "https://app.gitpod.io",
  "sub": "organization_id:a1b2c3d4-...:user_id:b3c4d5e6-...",
  "aud": ["sts.amazonaws.com"],
  "exp": 1711929600,
  "iat": 1711926000,
  "account_id": "d7e8f9a0-0000-4000-8000-000000000002",
  "user_id": "b3c4d5e6-0000-4000-8000-000000000003",
  "organization_id": "a1b2c3d4-0000-4000-8000-000000000001",
  "email": "dev@example.com",
  "name": "Jane Doe",
  "idp": "https://accounts.google.com",
  "idp_claims": { "groups": ["engineering"] }
}

Service account tokens

Issued when a service account requests a token.

{
  "iss": "https://app.gitpod.io",
  "sub": "organization_id:a1b2c3d4-...:service_account_id:f0a1b2c3-...",
  "aud": ["sts.amazonaws.com"],
  "exp": 1711929600,
  "iat": 1711926000,
  "service_account_id": "f0a1b2c3-0000-4000-8000-000000000006",
  "organization_id": "a1b2c3d4-0000-4000-8000-000000000001",
  "name": "ci-bot"
}

Account tokens

Issued for account-level operations (not scoped to an organization).

{
  "iss": "https://app.gitpod.io",
  "sub": "account_id:d7e8f9a0-...",
  "aud": ["sts.amazonaws.com"],
  "exp": 1711929600,
  "iat": 1711926000,
  "account_id": "d7e8f9a0-0000-4000-8000-000000000002",
  "email": "admin@example.com",
  "name": "Jane Admin",
  "idp": "https://accounts.google.com",
  "idp_claims": { "groups": ["engineering", "platform"] }
}

Runner tokens

Issued for runner-level operations.

{
  "iss": "https://app.gitpod.io",
  "sub": "organization_id:a1b2c3d4-...:runner_id:f3a4b5c6-...",
  "aud": ["sts.amazonaws.com"],
  "exp": 1711929600,
  "iat": 1711926000,
  "runner_id": "f3a4b5c6-0000-4000-8000-000000000007",
  "organization_id": "a1b2c3d4-0000-4000-8000-000000000001",
  "runner_name": "us-east-prod"
}

Subject claim (`sub`)

The V3 sub claim uses a key:value pair format separated by colons:

organization_id:<orgID>:project_id:<projID>

Each principal type has default sub claim keys:

Principal	Default sub claim
Environment (with project)	`organization_id:<orgID>:project_id:<projID>`
Environment (without project)	`organization_id:<orgID>`
User	`organization_id:<orgID>:user_id:<userID>`
Service Account	`organization_id:<orgID>:service_account_id:<saID>`
Account	`account_id:<accountID>`
Runner	`organization_id:<orgID>:runner_id:<runnerID>`

Customizing the sub claim

You can add extra fields to the sub claim to create more specific trust policies. Configure extra sub fields on the OIDC Token Configuration page. Available extra sub fields:

Field	Description	Principals
`creator_id`	ID of the user who created the environment	Environment
`creator_principal`	Principal type of the creator	Environment
`creator_email`	Email of the creator	Environment
`creator_name`	Name of the creator	Environment
`creator_idp`	Identity provider URL of the creator	Environment
`account_id`	Account ID	Account, User
`user_id`	User ID	User
`organization_id`	Organization ID	All (already in default sub for most)
`project_id`	Project ID	Environment
`runner_id`	Runner ID	Runner, Environment
`environment_id`	Environment ID	Environment
`email`	Email of the principal	User, Account
`name`	Name of the principal	User, Account, ServiceAccount
`idp`	Identity provider URL	User, Account
`runner_name`	Name of the runner	Runner
`service_account_id`	Service account ID	ServiceAccount
`environment_initializers.git.remote_uri`	Git remote URI	Environment
`environment_initializers.git.upstream_remote_uri`	Upstream git remote URI	Environment
`environment_initializers.context_url`	Context URL	Environment

For example, adding creator_email produces a sub like:

organization_id:<orgID>:environment_id:<envID>:creator_email:dev@example.com

This lets you write trust policies that restrict access to environments created by a specific developer.

Setting up OIDC authentication

Setting up OIDC authentication involves three steps:

Register Ona as an identity provider with your cloud provider or third-party service. Use https://app.gitpod.io as the issuer URL.
Configure trust rules that define which token claims are required for access. Use the sub claim and other flat claims to implement fine-grained access control.
Exchange the token from within an Ona environment using the CLI. The cloud provider validates the token against Ona’s JWKS endpoint and issues short-lived credentials.

Provider-specific guides

CLI usage

Retrieve a token using ona idp token:

ona idp token --audience sts.amazonaws.com

Decode the token to inspect claims:

ona idp token --audience sts.amazonaws.com --decode

Use ona idp login for provider-specific authentication:

# AWS
ona idp login aws --role-arn arn:aws:iam::123456789012:role/OnaRole

# HashiCorp Vault
ona idp login vault --role my-role

OIDC discovery endpoint

Ona exposes a standard OIDC discovery endpoint at:

https://app.gitpod.io/.well-known/openid-configuration

The JSON Web Key Set (JWKS) for verifying token signatures is at:

https://app.gitpod.io/.well-known/jwks.json

The discovery endpoint returns the full list of supported claims, including all V3 claims:

{
  "issuer": "https://app.gitpod.io",
  "authorization_endpoint": "https://app.gitpod.io/auth/oauth2/authorize",
  "token_endpoint": "https://app.gitpod.io/auth/oauth2/token",
  "jwks_uri": "https://app.gitpod.io/.well-known/jwks.json",
  "scopes_supported": ["openid"],
  "response_types_supported": ["code", "id_token", "token"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256"],
  "claims_supported": [
    "sub", "iss", "aud", "exp", "iat",
    "org", "gsub",
    "account_id", "user_id", "organization_id", "project_id",
    "runner_id", "runner_manager_id", "environment_id", "service_account_id",
    "environment_initializers",
    "creator_principal", "creator_id", "creator_email", "creator_name",
    "creator_idp", "creator_idp_claims",
    "email", "name", "idp", "idp_claims",
    "runner_name"
  ],
  "code_challenge_methods_supported": ["S256"]
}

V2 tokens

V2 is the previous token format. New integrations should use V3 tokens. V2 tokens remain fully supported and will continue to work. They do not receive new claims or features.

V2 tokens use a different sub claim format and include fewer claims. If your organization currently uses V2 tokens, existing integrations will continue to function without changes.

V2 subject claim format

The V2 sub claim uses a path-based format:

Users: org:<orgID>/user:<userID>
Runners: org:<orgID>/rnr:<runnerID>
Environments without a project: org:<orgID>/env:<environmentID>
Environments from a project: org:<orgID>/prj:<projectID>/env:<environmentID>

V2 token example

{
  "aud": "example.org",
  "exp": 1740517845,
  "iat": 1740514245,
  "iss": "https://app.gitpod.io",
  "org": "0191e223-1c3c-7607-badf-303c98b52d2f",
  "sub": "org:0191e223-1c3c-7607-badf-303c98b52d2f/prj:019527e4-75d5-704d-a5a4-a2b52cf56198/env:019527e4-75d5-704d-a5a4-a2b52cf56196",
  "gsub": { "principal": "environment", "id": "019527e4-75d5-704d-a5a4-a2b52cf56196" }
}

V2 access control

You can match on the sub claim prefix to control access:

All environments in an org: match org:<orgID>/*
Environments from a project: match org:<orgID>/prj:<projectID>/*
A specific environment: match the full sub value

For V2-specific cloud provider setup, see the V2 AWS guide. Read more:

[Auth0 docs] OpenID Connect Protocol

Get Started

Using Ona

Configuration

Administration & Security

Infrastructure

Billing

Learn

Reference

Support

Releases

Enable V3 tokens

Token structure

Environment tokens

User tokens

Service account tokens

Account tokens

Runner tokens

Subject claim (`sub`)

Customizing the sub claim

Setting up OIDC authentication

Provider-specific guides

CLI usage

OIDC discovery endpoint

V2 tokens

V2 subject claim format

V2 token example

V2 access control

Get Started

Using Ona

Configuration

Administration & Security

Infrastructure

Billing

Learn

Reference

Support

Releases

Documentation Index

​Enable V3 tokens

​Token structure

​Environment tokens

​User tokens

​Service account tokens

​Account tokens

​Runner tokens

​Subject claim (sub)

​Customizing the sub claim

​Setting up OIDC authentication

​Provider-specific guides

​CLI usage

​OIDC discovery endpoint

​V2 tokens

​V2 subject claim format

​V2 token example

​V2 access control

Enable V3 tokens

Token structure

Environment tokens

User tokens

Service account tokens

Account tokens

Runner tokens

Subject claim (`sub`)

Customizing the sub claim

Setting up OIDC authentication

Provider-specific guides

CLI usage

OIDC discovery endpoint

V2 tokens

V2 subject claim format

V2 token example

V2 access control