OIDC Integrations

OIDC is a protocol for authenticating entities between systems. Spiral integrates with several OIDC providers to allow workloads to authenticate without managing static credentials.

For general workload setup steps (creating a workload, policy, and grant), see Workloads.

OIDC tokens must be issued with the audience (aud) claim set to https://iss.spiraldb.com. The built-in integrations (GitHub, GCP) request this audience automatically. Modal is the exception — Modal tokens are always issued with audience oidc.modal.com, and Spiral accounts for this.

GitHub Actions

GitHub Actions workflows can authenticate to Spiral using GitHub’s OIDC tokens .

Create a workload policy matching tokens from a specific repository:


spiral workloads create-policy github work_p9cqam --repository vortex-data/vortex

In your GitHub Actions workflow, request an OIDC token and set the workload ID:


permissions:
  id-token: write
 
env:
  SPIRAL_WORKLOAD_ID: work_p9cqam

For more on GitHub’s OIDC claims, see Understanding the OIDC token .

Modal functions can authenticate to Spiral using Modal’s OIDC tokens .

Create a workload policy matching tokens from a specific workspace and environment:


spiral workloads create-policy modal work_p9cqam --workspace-id ws-12345abcd --environment-name main

In your Modal function, set the workload ID:


export SPIRAL_WORKLOAD_ID=work_p9cqam

For more on Modal’s OIDC claims, see Understanding your OIDC claims .

GCP

GCP service accounts can authenticate to Spiral using GCP metadata identity tokens .

Create a workload policy matching tokens from a specific service account:


spiral workloads create-policy gcp work_p9cqam \
    --email my-sa@my-project.iam.gserviceaccount.com \
    --unique-id 107691503500061507150

Your code must be running on a Google Cloud service that provides metadata identity tokens:

Compute Engine
App Engine (standard and flexible)
Cloud Run / Cloud Run functions
Google Kubernetes Engine (see GKE below)
Cloud Build

GKE

Google Kubernetes Engine pods authenticate through GCP IAM service account impersonation. The GKE Kubernetes service account impersonates a GCP IAM service account, and that GCP IAM service account is the identity matched by the workload policy.

Enable Workload Identity Federation for your GKE cluster.
Grant your GKE service account impersonation rights on a GCP IAM service account. We recommend creating a dedicated GCP IAM service account for this. You may use roles/iam.serviceAccountOpenIdTokenCreator instead of roles/iam.workloadIdentityUser.
Create a workload and policy for the GCP IAM service account (the one being impersonated), and grant it access to your project. The policy should match the GCP IAM service account, not the GKE Kubernetes service account.
Set the workload ID in your pod’s environment:
```
export SPIRAL_WORKLOAD_ID=work_p9cqam
```

AWS

AWS IAM roles can authenticate to Spiral using STS (Security Token Service).

AWS authentication uses STS rather than OIDC, but the setup follows the same workload and policy pattern.

Create a workload policy matching a specific IAM role:


spiral workloads create-policy aws work_p9cqam --account 123456789012 --role MyDeployRole

Your code must be running with the specified IAM role assumed (e.g. via EC2 instance role, ECS task role, or Lambda execution role).

In your AWS environment, set the workload ID:


export SPIRAL_WORKLOAD_ID=work_p9cqam

OIDC

If your identity provider is not listed above, you can create a policy with a custom OIDC provider.

Create a workload policy with a custom issuer and claim conditions:


spiral workloads create-policy oidc work_p9cqam \
    --iss https://login.example.com \
    --conditions sub=service-account-1 \
    --conditions email=bot@example.com

In your environment, set the workload ID and the OIDC token issued by your provider:


export SPIRAL_WORKLOAD_ID=work_p9cqam
export SPIRAL_OIDC_PROVIDER_TOKEN=<token from your OIDC provider>

The pyspiral client detects SPIRAL_OIDC_PROVIDER_TOKEN and automatically exchanges it for a Spiral JWT.

Your OIDC provider must issue tokens with the audience (aud) claim set to https://iss.spiraldb.com.