Skip to main content
Requires Enterprise plan. Contact sales for access.
You can use OIDC authentication to connect Ona environments to cloud providers or third parties such as AWS, Azure, GCP, or secret management services like Vault. OIDC integration eliminates the need to manually distribute access credentials, secrets, and other key material via environment variables or other methods. OIDC tokens are scoped to the environment, not the runner. This means OIDC works with both Ona Cloud and self-hosted runners.

​
OIDC Discovery Endpoint

Ona exposes an OIDC discovery endpoint at: 
https://app.gitpod.io/.well-known/openid-configuration
This endpoint returns the OIDC provider metadata required to configure trust with third-party services: 
{
  "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"]
}
The JSON Web Key Set (JWKS) for verifying token signatures is available at: 
https://app.gitpod.io/.well-known/jwks.json

​
Setting up OIDC Authentication with a third party

Setting up OIDC Authentication generally involves three main steps:
  1. Establish Trust: Register Ona with your OIDC-supported third party (like AWS, Google, etc.). This third party becomes the audience in your JWT token generated in Ona.
  2. Setup Trust Rules: Configure what the JWT claims must contain to be exchanged for a valid auth token. Here you can implement fine-grained access controls.
  3. Exchange the JWT token: Once trust and trust rules are established, use the JWT tokens generated by the gitpod idp token command to authenticate with the third party.

​
Provider specific guides

Read more:

​
CLI integration

You can retrieve a JWT token for OIDC using gitpod idp. To retrieve the OIDC token for the current environment, run gitpod idp token. For example, to request a new OIDC JWT for example.org, execute: 
$ gitpod idp token --audience example.org
eyJhbGciOiJSUzI1NiIsImtpZCI6ImlkLTE2ODQ3NTc4MDY...
To decode the output, use the --decode flag: 
$ gitpod idp token --audience example.org --decode
Once decoded, the result will resemble this JSON object: 
{
	"Claims": {
		"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"
	},
	"Header": [
		{
			"KeyID": "k0",
			"JSONWebKey": null,
			"Algorithm": "RS256",
			"Nonce": "",
			"ExtraHeaders": null
		}
	]
}

​
Access Control Examples

​
Subject claim format

Depending on the principal, the sub claim has the following 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>

​
Granting access to anyone in the organization

You can configure your third-party service to grant access based on the org:<orgID> prefix.

​
Granting access to an Environment created from a specific project

You can grant your third-party service access to an environment created from a specific project by matching the org:<orgID>/prj:<projectID> prefix.

​
Grant access to a specific Environment

You can grant your third-party service access to a specific environment by matching the org:<orgID>/prj:<projectID>/env:<environmentID> prefix.