OIDC concepts

This page explains how workload identity federation works in Thalassa Cloud — the concepts, vocabulary, and access control model. Read this before configuring identity providers or federated identities.

The problem OIDC solves

CI/CD pipelines and other automated systems need to call the Thalassa Cloud API. The traditional approach is to create service account access credentials (a client ID and secret) and store them in GitHub Secrets, GitLab CI variables, or a vault.

That works, but long-lived secrets in CI are risky: they can leak through logs, forked PRs, or misconfigured workflows, and they require manual rotation.

Workload identity federation removes the secret from CI. Instead, your pipeline receives a short-lived OIDC ID token from the CI platform (GitHub, GitLab, etc.). Thalassa Cloud validates that token and, if it matches your rules, returns a bearer access token that acts as a specific service account.

In one sentence: your CI job proves who it is with a JWT; Thalassa Cloud checks that proof and issues a token that impersonates a service account you configured.

How the flow works

    sequenceDiagram
    participant CI as CI platform
    participant TC as Thalassa Cloud API
    participant SA as Service account

    CI->>CI: Job starts, issues OIDC ID token
    CI->>TC: POST /oidc/token (ID token + org + SA ID)
    TC->>TC: Verify signature (JWKS), issuer, audience, claims
    TC->>CI: Bearer access token (short-lived)
    CI->>TC: API call with bearer token
    TC->>SA: Evaluate SA roles + token scopes
    TC->>CI: Response
  

1. CI platform issues an ID token — A signed JWT that describes the job (repository, branch, environment, etc.).
2. Pipeline exchanges the token — Sends the ID token to https://api.thalassa.cloud/oidc/token.
3. Thalassa Cloud validates and matches — Checks the signature, issuer, audience, and claim rules on the federated identity.
4. Bearer token is returned — A short-lived Thalassa Cloud access token scoped to the service account.
5. API calls use the bearer token — Same as any other Thalassa Cloud API authentication.

The cast of characters

Why two configuration steps?

Engineers often ask why there is both an identity provider and a federated identity. They serve different purposes:

One identity provider (e.g. github-actions) can back many federated identities on different service accounts, each with different claim matching rules.

OIDC federation vs access credentials

For production pipelines, use OIDC federation. Use access credentials when you need a simple static secret for a system that cannot obtain OIDC ID tokens (for example, a long-running service outside CI).

See Service Accounts for creating and managing access credentials.

Three layers of access control

After a successful token exchange, three separate mechanisms control what the pipeline can do. Confusing these is a common source of “token exchange worked but API call failed” issues.

All three must allow an action for it to succeed:

1. The CI job’s ID token must match the federated identity rules.
2. The returned bearer token must include the required API scope.
3. The service account must have the IAM permission for the resource and action.

API scopes can narrow access below what the service account’s IAM roles allow, but they cannot grant permissions the service account does not have.

Glossary

Decode your ID token

When claim matching fails, decode the ID token to see what the CI platform actually issued:

# Print the JWT payload (middle segment) as JSON
echo "${OIDC_TOKEN}" | cut -d. -f2 | base64 -d 2>/dev/null | jq

On macOS, if base64 -d fails, use base64 -D instead.

Compare the output to your federated identity configuration:

Example: GitHub Actions token

A token from a push to main on myorg/myrepo might contain:

{
  "iss": "https://token.actions.githubusercontent.com",
  "sub": "repo:myorg/myrepo:ref:refs/heads/main",
  "aud": "https://api.thalassa.cloud",
  "repository": "myorg/myrepo",
  "repository_owner": "myorg",
  "ref": "refs/heads/main"
}

A matching federated identity would use:

• Trusted Audiences: https://api.thalassa.cloud
• Subject claim: repo:myorg/myrepo:ref:refs/heads/main

And the GitHub workflow must request the token with the same audience (see GitHub Actions and GitLab CI guides).

Project context

Many Thalassa Cloud resources are scoped to a project. When calling project-scoped APIs, set the active project using one of:

• X-Project-Identity header
• OIDC project claim on the bearer token (if configured)
• ?project= query parameter

Without a project context, only organisation-scoped resources and organisation-level permissions apply. See IAM policy concepts for how project context affects permission checks.

Related documentation

• Create Identity Provider — Configure trust in an external OIDC issuer
• Create Federated Identity — Link a provider to a service account with claim rules
• Troubleshooting — Diagnose token exchange and permission failures
• Service Accounts — Create service accounts and access credentials
• RBAC roles — Assign permissions to service accounts