Workload identity federation

Workload identity federation lets trusted workloads exchange externally issued identity tokens for short-lived OpenAI access tokens. Use these guides to configure your external identity provider, create OpenAI service account mappings, and authenticate workloads without storing long-lived API keys.

For token exchange request and response details, authorization behavior, and current limitations, see the workload identity token exchange reference.

How it works

Workload identity federation has four parts:

1. A workload identity provider describes the trusted issuer. It stores the expected OIDC issuer, audience, and key source used to verify external subject tokens.
2. A service account mapping authorizes specific external token attributes to mint tokens for a particular OpenAI service account within a project.
3. A token exchange request sends the external subject token to OpenAI and returns a short-lived OpenAI access token.
4. The workload uses the OpenAI-issued access token as a bearer credential to authenticate requests to the OpenAI API.

You must be an organization owner to configure this feature. To access it, go to Organization Settings > Security > Workload Identity Provider. Configure service account mappings from the workload identity provider details page.

Choose a setup guide

Start with the guide that matches where your workload runs:

OpenAI supports OIDC-compatible JWT subject tokens in the documented configurations. If you need an OIDC provider that isn’t listed, contact us.

Each provider guide shows how to issue and inspect a subject token on that platform, and how to configure the OpenAI SDK to exchange it for a short-lived OpenAI access token.

Configure a Workload Identity Provider

Create a Workload Identity Provider for each external issuer you trust. Workload identity federation supports OIDC JWT subject tokens.

Workload Identity Provider configuration includes these dashboard options:

Transform token claims with CEL

Attribute transformations use Common Expression Language (CEL). OpenAI supports the standard CEL operators specified in langdef.md and doesn’t add custom workload identity federation-specific functions. Each expression receives one root object:

• assertion: The verified JWT claim set.

In the dashboard, the openai. prefix is applied automatically. Enter the suffix, such as subject, and an expression, such as assertion.sub. The API stores the derived attribute as openai.subject.

1
2
3
4
5
6
7
8
9
10
[
  {
    "attribute": "openai.subject",
    "expression": "assertion.sub"
  },
  {
    "attribute": "openai.repository",
    "expression": "assertion.repository"
  }
]

Use CEL syntax defined by the CEL language specification. For example, you can read claim values with expressions such as assertion.sub or assertion.repository. Unsupported syntax or functions fail mapping resolution.

1
2
3
4
5
6
7
8
9
10
[
  {
    "attribute": "openai.repository_ref",
    "expression": "assertion.repository + \"@\" + assertion.ref"
  },
  {
    "attribute": "openai.production",
    "expression": "assertion.ref == \"refs/heads/main\""
  }
]

Transformation results must be scalar values: strings, booleans, integers, or finite numbers. Arrays, objects, null values, and evaluation errors fail mapping resolution. OpenAI converts scalar transformation results to strings before comparing them to mapping values. For example, true becomes "true" and 7 becomes "7".

Mapping keys that start with openai. resolve only from attribute transformations. Raw subject token claims that already use an openai. prefix don’t affect mapping decisions unless you configure a matching transformation.

Manage JWKS and key rotation

OpenAI verifies OIDC subject tokens with the key source configured on the Workload Identity Provider.

• OIDC discovery: OpenAI fetches the issuer’s /.well-known/openid-configuration, then fetches the discovered jwks_uri. Discovery documents and remote JWKS payloads are cached for 600 seconds.
• Key refresh on miss: If a token kid isn’t found in the cached JWKS, OpenAI refreshes the JWKS and tries the lookup again before rejecting the token.
• Uploaded JWKS: When Use uploaded JWKS for token verification is enabled, OpenAI uses the uploaded JWKS stored on the Workload Identity Provider and doesn’t perform OIDC discovery or remote JWKS fetching. After a provider update is saved and available to token exchange, new exchanges use the saved JWKS.
• Multiple keys: A JWKS can contain multiple public keys, and each key must have a unique non-empty kid.

During signing-key rotation, publish both old and new public keys in the issuer JWKS during the rotation window. This lets tokens signed by the old key continue working while OpenAI accepts tokens signed by the new key. For uploaded JWKS mode, update the Workload Identity Provider JWKS before issuing tokens with the new kid; OpenAI rejects tokens signed by a key absent from the configured JWKS.

Configure service account mappings

A service account mapping defines which external identities can mint access tokens for an OpenAI service account.

Mapping configuration includes these dashboard options:

Attribute assertion values must be scalar JSON values. String values may use one trailing wildcard, such as repo:example/*. The wildcard must have a non-empty prefix; * by itself isn’t supported.

Valid wildcard values:

• repo:openai/*
• repository:my-org/*

Invalid wildcard values:

• *
• repo:*:prod
• repo/*/main

The dashboard shows mapping-level restrictions as Permissions. Token exchange responses expose the same restrictions as OAuth scopes in the scope property. Admin API scopes can’t be assigned to Workload Identity Provider mappings, and downstream API authorization still applies after OpenAI mints a token.

Mapping resolution example

Mapping resolution starts after OpenAI verifies the external subject token. OpenAI looks up mappings for the requested identity_provider_id and service_account_id, skips disabled mappings, evaluates only the attributes needed by each mapping, and issues a token only if exactly one enabled mapping matches all configured attributes.

For example, a GitHub Actions token might contain these claims:

1
2
3
4
5
6
7
{
  "iss": "https://token.actions.githubusercontent.com",
  "aud": "https://api.openai.com/v1",
  "sub": "repo:my-org/my-repo:ref:refs/heads/main",
  "repository": "my-org/my-repo",
  "ref": "refs/heads/main"
}

The Workload Identity Provider can define a derived attribute:

1
2
3
4
5
6
[
  {
    "attribute": "openai.repository_ref",
    "expression": "assertion.repository + \"@\" + assertion.ref"
  }
]

Then a service account mapping can require both raw and derived attributes:

This mapping matches only when all three attributes match. The sub value uses a trailing wildcard, so it matches any value with the prefix repo:my-org/my-repo:. The openai.repository_ref key resolves from the attribute transformation; OpenAI doesn’t use a raw token claim named openai.repository_ref.

If multiple enabled mappings match the same token exchange, OpenAI rejects the exchange. OpenAI enforces a unique mapping for each (provider, service account) pair and doesn’t combine permissions across multiple mappings.

Security recommendations

• Use a dedicated OpenAI service account for each application or workload.
• Separate production and non-production environments.
• Prefer exact claim matching over broad attribute patterns.
• Grant only the minimum OpenAI permissions required.
• Review and remove unused mappings regularly.
• Monitor token exchange failures and unexpected access patterns.
• Avoid sharing identities across unrelated workloads.