OIDC Workload Identity

Workload Identity Federation in Thalassa Cloud enables service account impersonation through OIDC (OpenID Connect) identity providers. This allows you to exchange identity tokens from external systems (such as GitHub Actions) for Thalassa Cloud bearer tokens without managing long-lived credentials.

Workload Identity Federation is useful for:

• Authenticating CI/CD pipelines (e.g., GitHub Actions, GitLab CI)
• Using tools like Terraform securely without storing credentials
• Automating deployments safely
• Using identity providers from other clouds

How It Works

Workload Identity Federation uses the standard OIDC token exchange flow:

1. Identity Provider: Your external system (e.g., GitHub Actions) generates an OIDC ID token
2. Token Exchange: The ID token is exchanged with Thalassa Cloud for a bearer token
3. Service Account Impersonation: The bearer token allows impersonation of a configured service account
4. API Access: Use the bearer token to access Thalassa Cloud APIs with the service account’s permissions

Supported Features

Thalassa Cloud’s Workload Identity Federation supports:

Setup Process

Workload Identity Federation requires a two-step setup process:

1. Create an Identity Provider: Configure the OIDC issuer and JWKS settings for your external identity provider
2. Create a Federated Identity: Link the identity provider to a service account with token matching rules and API scopes

Provider-Specific Configuration Guides

For detailed step-by-step instructions on configuring workload identity federation for specific providers, see:

Using OIDC

Token Exchange Flow

Once configured, you can exchange OIDC tokens for Thalassa Cloud bearer tokens using the OIDC token exchange grant:

1. Obtain OIDC Token: Get an ID token from your identity provider
2. Exchange Token: Send the ID token to Thalassa Cloud’s /oidc/token endpoint using the OIDC token exchange grant
3. Receive Bearer Token: Thalassa Cloud validates the token and returns a bearer token
4. Use Bearer Token: Include the bearer token in API requests or CLI commands

Token Exchange Request

The token exchange request requires:

• Grant Type: urn:ietf:params:oauth:grant-type:token-exchange (OIDC token exchange grant)
• Subject Token: The OIDC ID token from your identity provider
• Subject Token Type: urn:ietf:params:oauth:token-type:id_token
• Organisation ID: Your Thalassa Cloud organisation identifier (can be found in the Console or via tcloud me organisations)
• Service Account ID: The ID of the service account you want to impersonate (can be found in the IAM → Service Accounts section of the Console)

The request should be sent as application/x-www-form-urlencoded to the /oidc/token endpoint. The response will contain an access_token field with the bearer token that can be used for API authentication.

If a matching identity (valid token, subject, claim conditions, and audience all match) has been configured for the service account, you will receive a bearer access token, allowing you to access the API.

Token Lifetime

By default, access tokens returned through OIDC token exchange are valid for 1 hour. This is configurable through access_token_lifetime, allowing you to request tokens anywhere from 5 minutes through a maximum of 24 hours.

The format is <amount of seconds>s, or <amount of hours>h.

Example: Basic Token Exchange

# Exchange OIDC token for bearer token
BEARER_TOKEN=$(curl -X POST https://api.thalassa.cloud/oidc/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  -d "subject_token=${OIDC_TOKEN}" \
  -d "subject_token_type=urn:ietf:params:oauth:token-type:id_token" \
  -d "organisation_id=${THALASSA_ORGANISATION_ID}" \
  -d "service_account_id=${THALASSA_SERVICE_ACCOUNT_ID}" | jq -r '.access_token')

# Use the bearer token with tcloud CLI
tcloud --access-token="${BEARER_TOKEN}" kubernetes list

Example: Using with Terraform

Configure Terraform to use the bearer token:

terraform {
  required_providers {
    thalassa = {
      source  = "thalassa-cloud/thalassa"
      version = "~> 0.14"
    }
  }
}

provider "thalassa" {
  api_endpoint = "https://api.thalassa.cloud"
  access_token = var.thalassa_access_token  # Pass the exchanged bearer token
}

For provider-specific examples and detailed configuration, see the provider-specific guides above.

Security Considerations

Best Practices

1. Least Privilege: Configure OIDC impersionation with Federated identities with the minimum required permissions
2. Token Matching: Use specific subject claims and additional claim matching to restrict access
3. Scope Limitation: Only grant necessary API scopes

JWKS Security

For JWKS endpoints (https URLs), the JWKS content it fetched automatically, but when providing an offline JWKS JSON document you must update it manually. Only use custom JWKS content for offline scenarios when absolutely necessary.