Can I Use OIDC Authentication with CircleCI?

Yes! We have added the ability to use OIDC authentication in your CircleCI builds! In this article, we have consolidated some resources, as well as common problems that may arise along the way. We hope this will help assist you in implementing this feature.

OIDC tokens are automatically created and imported into your jobs.

Common Issues:

Prerequisites and Setup Checklist

Before diving into specific errors, verify the following baseline requirements are met:

CircleCI organization ID is correct (UUID format). Find it at Organization Settings > Overview.
The OIDC Identity Provider in your cloud platform uses the correct issuer URL:
- Cloud: https://oidc.circleci.com/org/<organization_id>
- Server: https://<your-circleci-server-hostname>/org/<organization_id>
The audience (aud) claim matches your CircleCI organization ID (Cloud default).
Your cloud IAM role or workload identity is configured to trust the CircleCI OIDC provider.
The job accesses $CIRCLE_OIDC_TOKEN or $CIRCLE_OIDC_TOKEN_V2 (not both are always needed—check which claim format your trust policy expects).
CircleCI Server version is 4.4 or higher (OIDC is not supported on earlier versions or air-gapped installs).

Failed to assume role

An error occurred (AccessDenied) when calling the AssumeRoleWithWebIdentity operation:
Not authorized to perform sts:AssumeRoleWithWebIdentity
Failed to assume role

One way to address this error is to ensure sure the token has the necessary permissions.

Token Versions: V1 vs V2

CircleCI provides two OIDC token environment variables. Using the wrong one for your trust policy conditions is a very common source of errors.

Variable	$CIRCLE_OIDC_TOKEN (V1)	$CIRCLE_OIDC_TOKEN_V2 (V2)
sub claim format	org/<org_id>/project/<proj_id>/user/<user_id>	org/<org_id>/project/<proj_id>/user/<user_id>/vcs-origin/<vcs>/vcs-ref/<ref>
Best for	Broad org/project-level access	Branch-level restrictions (e.g., main only)

Helpful Resources:

Troubleshooting OIDC in CircleCI