OIDC

Outcome: Workloads can call Formal APIs with IdP JWTs and mint connector access tokens.
Prerequisites: A Formal machine user, and an IdP that can mint OIDC JWTs.

Overview

OIDC integrations let external workloads authenticate to the Formal with short-lived identity-provider JWTs. Formal verifies the token, evaluates a claim condition, and maps the caller to a configured machine user. The same trust can mint a short-lived federation token. Use that credential to access data through a Formal — without long-lived Formal API keys or machine access tokens. Use this for remote workloads such as GitHub Actions, GitLab, Terraform, SPIFFE workloads, E2B sandboxes, Modal Functions, or the Kubernetes Operator.

OIDC integrations are separate from SSO. SSO covers human Control Plane login. OIDC integrations cover machine authentication to core APIs and optional federated connector access.

How It Works

You create an OIDC integration with an issuer, machine user, and claim condition.
Formal returns an audience value: oidc.formal.ai/<integration_id>.
Your identity provider issues a JWT with that exact aud claim.
The caller presents the JWT as a Bearer token to Formal core APIs.
Formal verifies signature, issuer, audience, time claims, and the claim condition.
The request runs as the integration’s machine user.
Optionally, the caller mints a federation token and connects through a Connector.

Fixed IdP Audiences

Some identity providers do not let callers customize the JWT aud claim. These callers must select the integration with a request header:

X-Formal-OIDC-Integration-Id: integrationoidc_...

Formal then verifies the issuer, signature, expiry, and claim condition. The claim condition must verify the provider’s audience and stable workload identity claims.

Do not use claim_condition = "true" with header selection. Any valid token from the configured issuer could otherwise authenticate, even when issued for another service or workload.

For Spacelift, the audience is your account hostname. Prefer stable custom claims instead of comparing the complete sub, which varies by run type and scope:

claims.aud == "demo.app.spacelift.io" &&
claims.spaceId == "<SPACE_ID>" &&
claims.callerType == "stack" &&
claims.callerId == "<STACK_ID>"

Get these values from the Spacelift stack and space settings. See Spacelift’s OIDC claim reference for claim formats. Send the fixed-audience token and integration ID together:

curl -X POST \
  "https://api.formal.ai/core.v1.ConnectorService/CreateFederationToken" \
  -H "Authorization: Bearer ${SPACELIFT_OIDC_TOKEN}" \
  -H "X-Formal-OIDC-Integration-Id: <INTEGRATION_ID>" \
  -H "Content-Type: application/json" \
  -d '{}'

Verify: The request succeeds only for the configured account, space, and stack. Changing any checked claim returns 401 Unauthorized. The Formal Terraform provider can read Spacelift’s token and send the header:

provider "formal" {
  oidc {
    audience = "oidc.formal.ai/<INTEGRATION_ID>"
    env      = "SPACELIFT_OIDC_TOKEN"
  }
}

If a token contains a Formal audience and the header, both integration IDs must match. Formal performs this check and rejects conflicting values.

Setup in the Control Plane

Go to OIDC.
Click Create Integration.
Fill in:
- Name — unique friendly name in your org
- Issuer — absolute HTTPS issuer URL
- JWKS URI — optional; leave empty to use OIDC Discovery
- Machine User — Formal principal that authenticated tokens map to
- Claim Condition — CEL expression over claims (default true)
- End-User Email Expression — optional CEL that returns an email string
- Status — active or draft (draft disables auth)
Copy the Audience value shown after create.
Configure your identity provider to mint tokens with that audience.

Verify: Create succeeds and the audience appears as oidc.formal.ai/integrationoidc_….

Claim Conditions

Claim conditions are CEL expressions that must return a boolean. Verified JWT claims are available under claims.

If your OIDC issuer lets you set aud, request a dedicated audience for Formal and validate that exact value in claim_condition.

Examples:

true

claims.repo.startsWith('org/my-repo')

claims.sub == 'repo:formalco/monorepo:ref:refs/heads/main'

Failed, non-boolean, or invalid expressions deny authentication.

SPIFFE and SPIRE

SPIFFE workloads authenticate with a JWT-SVID. Formal verifies it like any other OIDC JWT, so the SPIFFE ID arrives as the sub claim. Formal fetches signing keys from the SPIRE OIDC Discovery Provider. Formal must reach it over public HTTPS on port 443.

1. Set the JWT-SVID issuer

Formal requires the token iss claim to match the integration issuer exactly. SPIRE omits iss unless you set jwt_issuer on the SPIRE server:

server {
  trust_domain = "example.org"
  jwt_issuer   = "https://oidc-discovery.example.org"
}

Use the same URL as a domains entry in the OIDC Discovery Provider config. Verify:

curl -s https://oidc-discovery.example.org/.well-known/openid-configuration | jq -r .issuer
# Expected: https://oidc-discovery.example.org

2. Create the integration

In OIDC, click Create Integration and choose the SPIFFE / SPIRE preset. Set Issuer to the jwt_issuer URL. Match the full SPIFFE ID in the claim condition:

claims.sub == 'spiffe://example.org/ns/prod/sa/deploy-bot'

To trust a group of workloads, match a path prefix that ends in /:

claims.sub.startsWith('spiffe://example.org/ns/prod/')

A prefix without a trailing / also matches sibling paths. For example, spiffe://example.org/ns/prod matches spiffe://example.org/ns/production.

3. Fetch a JWT-SVID for Formal

Request a JWT-SVID whose audience is the integration audience. SPIRE lets you set the audience, so you do not need X-Formal-OIDC-Integration-Id.

spire-agent api fetch jwt \
  -audience "oidc.formal.ai/<INTEGRATION_ID>" \
  -socketPath /run/spire/sockets/agent.sock

Verify: The output includes token(spiffe://example.org/...) followed by the JWT. Use it as the Bearer token for Formal APIs and CreateFederationToken. SPIRE issues JWT-SVIDs that expire after five minutes by default. Federation tokens minted from them expire at the same time.

4. Write policies on the SPIFFE ID

Connector policies read the SPIFFE ID from input.user.oidc.claims.sub:

package formal.v2

import future.keywords.if

default session := {
  "action": "block",
  "type": "block_with_formal_message"
}

session := {
  "action": "allow",
  "reason": "Trusted SPIFFE workload"
} if {
  input.user.oidc.claims.sub == "spiffe://example.org/ns/prod/sa/deploy-bot"
}

E2B Sandboxes

E2B Workload Identity gives each sandbox execution a short-lived JWT-SVID. On E2B Cloud, tokens use issuer https://id.e2b.dev and a sub in this format:

spiffe://id.e2b.dev/<PROJECT_ID>/<SANDBOX_ID>/<EXECUTION_ID>

1. Create the integration

In OIDC, click Create Integration and choose the E2B preset. Restrict the claim condition to your E2B project, with a trailing / so other projects cannot match:

claims.sub.startsWith('spiffe://id.e2b.dev/<PROJECT_ID>/')

For Bring Your Own Cloud (BYOC) deployments, set Issuer to your deployment’s issuer URL and use its SPIFFE trust domain in the claim condition.

2. Inject the token into Formal requests

Register a workload token with the integration audience, then add a network rule that injects it into HTTPS requests to Formal. E2B’s egress proxy adds the header, so sandbox code never handles the token:

from e2b import Sandbox, Secret

sandbox = Sandbox.create(
    iam={
        "tokens": {
            "formal": Secret.iam_token(
                audience="oidc.formal.ai/<INTEGRATION_ID>",
                token_type="JWT-SVID",
            ),
        },
    },
    network={
        "rules": {
            "api.formal.ai": [
                {
                    "transform": lambda ctx: {
                        "headers": {
                            "Authorization": f"Bearer {ctx.iam.tokens['formal']}"
                        },
                    },
                },
            ],
        },
    },
)

result = sandbox.commands.run(
    "curl -sS -X POST "
    "https://api.formal.ai/core.v1.ConnectorService/CreateFederationToken "
    "-H 'Content-Type: application/json' -d '{}'"
)

If your HTTP client uses its own CA bundle, configure it to trust the E2B egress proxy. See E2B’s TLS certificate guide. Verify: The response contains a federation token and username. Connector policies can read input.user.oidc.claims.project_id, input.user.oidc.claims.sandbox_id, and input.user.oidc.claims.template_id. Modal injects an identity token into every Function container as MODAL_IDENTITY_TOKEN. Sandboxes and Sidecars receive one only when created with include_oidc_identity_token=True. Modal tokens always use the fixed audience oidc.modal.com, so select the integration with the X-Formal-OIDC-Integration-Id header (see Fixed IdP Audiences).

1. Create the integration

In OIDC, click Create Integration and choose the Modal preset. Restrict the claim condition to your Modal workspace, and optionally an environment, app, or function:

claims.aud == 'oidc.modal.com' &&
claims.workspace_id == '<WORKSPACE_ID>' &&
claims.environment_name == 'main' &&
claims.app_name == 'my-app'

Find your workspace ID in Modal workspace settings or with modal token info.

2. Mint a federation token from a Function

import os

import modal
import requests

app = modal.App("formal-oidc")
image = modal.Image.debian_slim().pip_install("requests")


@app.function(image=image)
def federation_token():
    response = requests.post(
        "https://api.formal.ai/core.v1.ConnectorService/CreateFederationToken",
        headers={
            "Authorization": f"Bearer {os.environ['MODAL_IDENTITY_TOKEN']}",
            "X-Formal-OIDC-Integration-Id": "<INTEGRATION_ID>",
        },
        json={},
    )
    response.raise_for_status()
    return response.json()

Verify: The response contains a federation token and username. Connector policies can read Modal claims such as input.user.oidc.claims.app_name and input.user.oidc.claims.function_name.

Federated Connector Access

After an OIDC JWT authenticates to the control plane, call CreateFederationToken to mint a short-lived connector credential. Only OIDC-authenticated machine users can call this RPC. API keys and human sessions cannot mint federation tokens.

Mint a federation token

curl -X POST \
  "https://api.formal.ai/core.v1.ConnectorService/CreateFederationToken" \
  -H "Authorization: Bearer <OIDC_JWT>" \
  -H "Content-Type: application/json" \
  -d '{}'

Example response:

{
  "token": "<base64-encoded Formal JWT>",
  "username": "idp:formal:machine:ci-bot",
  "expires_at": "2026-08-06T03:00:00Z",
  "id": "fedtoken_...",
  "end_user_id": "user_..."
}

Field	Description
`token`	Connector password (base64-encoded Formal JWT)
`username`	Machine user’s Formal DB username
`expires_at`	Token expiry
`id`	Federated token ID (`fedtoken_…`)
`end_user_id`	Optional Formal human resolved from claims

Connect through a Connector

Use the response like any Formal username and access token:

psql "host=<CONNECTOR_HOST> port=5432 dbname=<DB> \
  user=<USERNAME> password=<FEDERATION_TOKEN>"

Replace <USERNAME> and <FEDERATION_TOKEN> with username and token from the mint response. Protocols that present the Formal JWT can authenticate immediately. Protocols that match stored credentials (for example some MySQL and S3 paths) need the token to sync to the Connector first. Retry briefly if auth fails right after mint.

Connect over SSH

Add the resource name after a + in the SSH username. Enter the password when prompted:

ssh -p <SSH_PORT> "<USERNAME>+<RESOURCE_NAME>@<CONNECTOR_HOST>"

OpenSSH truncates passwords longer than 1,023 bytes. Federation tokens carry the source claims, so they often exceed that limit. Use the hashed form of the token as the password instead. For example, with sshpass in automation:

export SSHPASS="formalhash:$(printf '%s' "$FEDERATION_TOKEN" | sha256sum | cut -d' ' -f1)"
sshpass -e ssh -p <SSH_PORT> "<USERNAME>+<RESOURCE_NAME>@<CONNECTOR_HOST>"

The hashed form matches tokens synced to the Connector, so retry briefly right after mint. Verify: The session opens, and SSH session policies can read input.user.oidc.claims.

Token lifetime and claims

Federation token expiry is:

min(upstream OIDC JWT exp, now + 1 hour)

Formal signs the federated JWT with:

Claim	Value
`aud`	`connectors.formal.ai`
`token_use`	`federated`
`sub`	Machine user ID
`end_user_id`	Optional Formal human user ID
`jti`	Federated token ID (`fedtoken_…`)
`oidc.integration_id`	OIDC integration ID for connector policy evaluation
`oidc.claims`	Verified claims from the source OIDC JWT

Evaluate connector policies with source claims

Connector policy evaluation over source OIDC claims requires Connector 2.16.1 or later.

The Connector exposes verified source claims under input.user.oidc:

input.user.oidc.integration_id
input.user.oidc.claims.*

Claims belong to the authenticated machine user. They do not appear under input.end_user. For example, this session policy allows only a specific GitHub repository and branch:

package formal.v2

import future.keywords.if

default session := {
  "action": "block",
  "type": "block_with_formal_message"
}

session := {
  "action": "allow",
  "reason": "Trusted repository and branch"
} if {
  input.user.oidc.claims.repository == "formalco/monorepo"
  input.user.oidc.claims.ref == "refs/heads/main"
}

Missing or mismatched claims leave the default block action in effect.

End-user attribution

Set End-User Email Expression when the workload acts for a human. The CEL expression runs over verified IdP claims and must return an email string. At mint time, Formal resolves that email to a Formal human user (case-insensitive). Sessions then use the machine user for credentials and the human user as the for policy and audit. On resources with linked accounts, the Connector sends the human user’s linked account. The workload then acts upstream as that person, so build the expression only from claims the workload can’t choose itself. Examples:

claims.owner_email

claims.sub.split('/').last()

Leave the expression empty for machine-only trusts. If the expression is set and resolution fails, mint fails closed — no token is issued.

Permissions and Audit

Verified OIDC callers expose claim context to Permissions as:

input.user.oidc.integration_id
input.user.oidc.issuer
input.user.oidc.claims.*

Control-plane audit events also record integration metadata and bounded claim JSON. They never store the raw JWT.

Terraform

You can manage the same resource with Terraform:

resource "formal_user" "ci" {
  type = "machine"
  name = "github-actions"
}

resource "formal_integration_oidc" "github_actions" {
  name            = "GitHub Actions"
  issuer          = "https://token.actions.githubusercontent.com"
  machine_user_id = formal_user.ci.id
  claim_condition = "claims.repository.startsWith(\"formalco/\")"

  # Optional: attribute federated connector sessions to a Formal human.
  # end_user_email_expression = "claims.owner_email"

  status = "active"
}

output "oidc_audience" {
  value = formal_integration_oidc.github_actions.audience
}

Verify:

terraform apply
terraform output oidc_audience
# Expected: oidc.formal.ai/integrationoidc_...

Troubleshooting

Requests return 401 Unauthorized

Possible causes:

Integration status is draft or deleted
Token aud does not exactly match oidc.formal.ai/<id>
Fixed-audience token omitted X-Formal-OIDC-Integration-Id
Issuer or JWKS does not match the integration
Claim condition evaluates to false
Machine user is inactive or deleted

Fix: Confirm the audience, set status to active, and validate issuer/JWKS/claims.

Discovery or JWKS fails

Possible causes:

Issuer is not HTTPS
Discovery endpoint is unreachable from Formal
JWKS URI is missing when discovery is unavailable

Fix: Set an explicit HTTPS JWKS URI, or fix the issuer discovery document.

SPIFFE JWT-SVIDs return 401 Unauthorized

Possible causes:

SPIRE server jwt_issuer is unset, so the JWT-SVID has no iss claim
jwt_issuer differs from the integration issuer, including a trailing /
The JWT-SVID audience is not oidc.formal.ai/<INTEGRATION_ID>

Fix: Set jwt_issuer to the integration issuer and restart the SPIRE server. Then fetch a new JWT-SVID with the integration audience.

CreateFederationToken returns failed precondition

Possible causes:

Caller used an API key instead of an OIDC Bearer JWT
Caller is not a machine user
Upstream OIDC JWT is expired
End-user email expression failed or matched no Formal human

Fix: Authenticate with a valid OIDC JWT for an active integration. If you set an end-user expression, confirm the claim value and that the human exists in Formal.

Connector rejects the federation token

Possible causes:

Token expired (min(OIDC exp, 1 hour))
Wrong Formal username (must be the mint response username)
Credential-match protocol used before the token synced

Fix: Mint a fresh token, use the returned username, and retry after a short sync delay for MySQL/S3-style auth paths.

SSH returns Permission denied

Possible causes:

OpenSSH truncated the federation token, which is longer than 1,023 bytes
The hashed token was used before it synced to the Connector
The token expired

Fix: Use the formalhash: form of the token as the password, and retry briefly after mint. Mint a new token if it expired.

Next Steps

Permissions

Authorize federated callers with claim-aware rules

Machine Users

Create the machine principal OIDC tokens map to

Connectors

Deploy Connectors that accept federation tokens

SSO

Configure human Control Plane login separately

Getting Started

Example Use Cases

AI Governance

Configuring Formal

Integrations

Configuration

Overview

How It Works

Fixed IdP Audiences

Setup in the Control Plane

Claim Conditions

SPIFFE and SPIRE

1. Set the JWT-SVID issuer

2. Create the integration

3. Fetch a JWT-SVID for Formal

4. Write policies on the SPIFFE ID

E2B Sandboxes

1. Create the integration

2. Inject the token into Formal requests

1. Create the integration

2. Mint a federation token from a Function

Federated Connector Access

Mint a federation token

Connect through a Connector

Connect over SSH

Token lifetime and claims

Evaluate connector policies with source claims

End-user attribution

Permissions and Audit

Terraform

Troubleshooting

Next Steps

Permissions

Machine Users

Connectors

SSO

​Overview

​How It Works

​Fixed IdP Audiences

​Setup in the Control Plane

​Claim Conditions

​SPIFFE and SPIRE

​1. Set the JWT-SVID issuer

​2. Create the integration

​3. Fetch a JWT-SVID for Formal

​4. Write policies on the SPIFFE ID

​E2B Sandboxes

​1. Create the integration

​2. Inject the token into Formal requests

​Modal

​1. Create the integration

​2. Mint a federation token from a Function

​Federated Connector Access

​Mint a federation token

​Connect through a Connector

​Connect over SSH

​Token lifetime and claims

​Evaluate connector policies with source claims

​End-user attribution

​Permissions and Audit

​Terraform

​Troubleshooting

​Next Steps

Permissions

Machine Users

Connectors

SSO

Overview

How It Works

Fixed IdP Audiences

Setup in the Control Plane

Claim Conditions

SPIFFE and SPIRE

1. Set the JWT-SVID issuer

2. Create the integration

3. Fetch a JWT-SVID for Formal

4. Write policies on the SPIFFE ID

E2B Sandboxes

1. Create the integration

2. Inject the token into Formal requests

Modal

1. Create the integration

2. Mint a federation token from a Function

Federated Connector Access

Mint a federation token

Connect through a Connector

Connect over SSH

Token lifetime and claims

Evaluate connector policies with source claims

End-user attribution

Permissions and Audit

Terraform

Troubleshooting

Next Steps