> ## Documentation Index > Fetch the complete documentation index at: https://ona.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # OpenID Connect (OIDC) > Access cloud providers and third-party services from Ona environments using OIDC tokens, without static credentials. > [!NOTE] > > Available on the Enterprise plan. [Contact sales](https://ona.com/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 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: 1. Open the [OIDC Token Configuration](https://app.gitpod.io/settings/security/oidc) page in your organization settings 2. Select **V3** as the token version 3. Optionally configure extra sub claim fields 4. Save > [!WARNING] > > Switching from V2 to V3 changes the `sub` claim format. Update your cloud provider trust policies before switching. See [V2 tokens](#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. ```json theme={null} { "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). ```json theme={null} { "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. ```json theme={null} { "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). ```json theme={null} { "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. ```json theme={null} { "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::project_id: ``` Each principal type has default sub claim keys: | Principal | Default sub claim | | - | - | | Environment (with project) | `organization_id::project_id:` | | Environment (without project) | `organization_id:` | | User | `organization_id::user_id:` | | Service Account | `organization_id::service_account_id:` | | Account | `account_id:` | | Runner | `organization_id::runner_id:` | ### 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](https://app.gitpod.io/settings/security/oidc) 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::environment_id::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: 1. **Register Ona as an identity provider** with your cloud provider or third-party service. Use `https://app.gitpod.io` as the issuer URL. 2. **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. 3. **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 * [AWS](https://ona.com/docs/ona/identity/aws-oidc.md) * [Azure](https://ona.com/docs/ona/identity/azure-oidc.md) * [GCP](https://ona.com/docs/ona/identity/gcp-oidc.md) * [HashiCorp Vault](https://ona.com/docs/ona/identity/vault-oidc.md) ## CLI usage Retrieve a token using `ona idp token`: ```bash theme={null} ona idp token --audience sts.amazonaws.com ``` Decode the token to inspect claims: ```bash theme={null} ona idp token --audience sts.amazonaws.com --decode ``` Use `ona idp login` for provider-specific authentication: ```bash theme={null} # 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: ```json theme={null} { "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 > [!NOTE] > > 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:/user:` * **Runners:** `org:/rnr:` * **Environments without a project:** `org:/env:` * **Environments from a project:** `org:/prj:/env:` ### V2 token example ```json theme={null} { "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:/*` * **Environments from a project:** match `org:/prj:/*` * **A specific environment:** match the full `sub` value For V2-specific cloud provider setup, see the [V2 AWS guide](https://ona.com/docs/ona/integrations/aws.md). **Read more:** * [\[Auth0 docs\] OpenID Connect Protocol](https://auth0.com/authenticate/protocols/openid-connect-protocol) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.