New OIDC Custom Claims

Build Environment
1

We’ve added 3 new custom claims to CircleCI’s OpenID Connect (OIDC) tokens to give you more flexibility and control when authenticating with cloud providers.

What’s new:

  • OIDC tokens now include three new claims:

    • oidc.circleci.com/org-id - Your organization identifier

    • oidc.circleci.com/pipeline-id - The pipeline identifier for the current run

    • oidc.circleci.com/pipeline-definition-id - The pipeline definition identifier

  • Available in both V1 and V2 token formats

  • The org-id claim is particularly useful if you need to customize the aud (audience) claim, which normally carries the organization ID

How to use it: These new claims are automatically included in your OIDC tokens—no configuration changes needed. You can access them the same way you would any other claim in your OIDC token validation logic.

Why this matters: These additional claims give you more granular control when setting up trust policies with cloud providers like AWS, GCP, and Azure. For example, you can now create IAM policies that restrict access based on specific pipelines or pipeline definitions, adding an extra layer of security to your infrastructure automation.

For more details on CircleCI’s OIDC implementation, see our OIDC documentation.