Documentation
Identity & Access Management
OIDC
Service Account Impersonation

Create Federated Identity On a Service Account

Federated identities link an identity provider to a specific service account, defining which tokens can impersonate that service account and what permissions they receive.

Prerequisites

Before creating a federated identity, ensure you have:

  1. An identity provider created (see Create Identity Provider)
  2. A service account with appropriate IAM roles (see Service Accounts)
  3. Knowledge of the token claims you want to match (subject, repository, branch, etc.)

Configuration Steps

Step 1: Navigate to Service Accounts

Navigate to IAM → Service Accounts in your Thalassa Cloud Console.

Step 2: Select Service Account

Select the service account you want to configure federation for.

Step 3: Create Federated Identity

Click “Federated Identities”, next click on “Create Federated Identity”

Step 4: Configure Federated Identity

Fill in the federated identity configuration:

Identity Provider:

  • Identity Provider: Select the identity provider you previously created)
  • This links the federated identity to your configured OIDC issuer

Token Matching:

Configure how tokens are matched to this federated identity:

  • Trusted Audiences: Configure which audiences (aud claim) are trusted. ID tokens not matching the audience will not be allowed to be matched.

    • Example; api.thalassa.cloud
    • Ensure that you configure the audience of the ID token the same. For example, GitHub or Gitlab let you configure the audience of the ID token provisioned in their pipeline / job.

  • Subject Claim: Specify the expected sub (subject) claim value

    • Example for GitHub Actions: repo:myorg/myrepo:ref:refs/heads/main
    • Supports wildcards for pattern matching
    • This is the primary claim used to match tokens

  • Additional Claims (Optional): Configure additional claims to match

    • Common claims: repository, repository_owner, ref, environment
    • Use claim matching to restrict access to specific repositories, branches, or environments
    • Example: Match tokens only from the main branch by setting ref: refs/heads/main

You are able to use * wildcards, such as repo:myorg/*:ref:refs/heads/main to match all repositories in the myorg GitHub group.

API Scopes:

Set the Thalassa Cloud API scopes to include in the returned bearer token:

  • API Scopes: Select one or more API scopes
    • Common scopes: api:read, api:write, containerRegistry:pull
    • Scope selection determines what actions the bearer token can perform
    • Follow the principle of least privilege: only grant the minimum scopes required. You can scope down also in the token exchange flow.

Lifecycle (Optional):

Configure an expiration date for when the federated identity should be automatically revoked:

  • Expiry Date: Set an optional expiration date
    • Useful for temporary access or project-based workloads
    • After expiry, token exchange will fail for this federated identity
    • Plan ahead for long-running workloads and set reminders to rotate

Step 5: Review and Save

  1. Review your configuration
  2. Click “Create Federated Identity” or “Save”
  3. The federated identity is now active and ready to use
Create Identity ProviderGitHub Actions