Using OpenID Connect Tokens in Jobs

You will need to allow your AWS account to trust CircleCI’s OpenID Connect tokens. To do this, create an Identity and Access Management (IAM) identity provider, and an IAM role in AWS (this is a one-time configuration).

Visit the Creating OpenID Connect (OIDC) identity providers page of the AWS docs and follow the instructions. You will need your CircleCI Organization ID, which you can find by navigating to Organization Settings > Overview on the CircleCI web app. Copy your Organization ID for the next step.

When asked for the Provider URL, enter: https://oidc.circleci.com/org/ORGANIZATION_ID, where ORGANIZATION_ID is the ID of your CircleCI organization. Provide the same CircleCI Organization ID for the Audience.

Next, you will need to create an IAM role. Visit the Creating a role for web identity or OIDC section of the AWS docs.

For the trusted entity, select Web Identity, then choose the identity provider that you created earlier. For Audience, choose the only option. Then, click on NEXT, which will take you to the Add Permissions page. This allows you to specify what your CircleCI jobs can and cannot do. Choose only permissions that your job will need, which is an AWS best practice.

Note: You may find it useful to create your own policy.

Now that you have set up an IAM role, you are ready to write a CircleCI job that authenticates with AWS using OIDC. This is accomplished by using CircleCI’s AWS CLI orb to generate temporary keys and configure a profile that uses OIDC. Orbs are reusable packages of YAML configuration that condense repeated pieces of configuration into a single line of code. In this case, the AWS CLI orb enables you to generate a temporary session token, AWS Access Key ID, and AWS secret access key with a single command in your configuration.

First, choose the CircleCI jobs in your workflow where you want to use OIDC. Make sure each of these jobs use a valid CircleCI context. The OpenID Connect token is available only to jobs that use at least one context. The context may contain no environment variables.

In your .circleci/config, be sure to import the aws-cli orb. Next, run the aws-cli/setup command in your job before interacting with any AWS services. You will need to provide the aws-cli/setup command with the role-arn associated with the role you have created in the step above along with your aws-region.

You can optionally provide a profile-name, role-session-name, and session-duration. If you provide a profile-name, the temporary keys and token will be configured to that specific profile. You must use that same profile-name with the rest of your aws commands. If a profile-name is not provided, the keys and token will be configured to the default profile.

Additionally, if you do not provide a role-session-name or session-duration, their default values are ${CIRCLE_JOB} (your job’s name) and 3600 seconds respectively.

Below is an example of a complete configuration with a job that configures a profile with OIDC and uses it to log into AWS ECR. The same profile can be used to run other AWS commands, such as S3, EKS, ECS, and more, as long as the role-arn has been configured with appropriate permissions.

You can take advantage of the format of the claims in CircleCI’s OIDC token to limit what your CircleCI jobs can do in AWS. For example, if certain projects should only be able to access certain AWS resources, you can restrict your IAM role so that only CircleCI jobs in a specific project can assume that role.

To do this, edit your IAM role’s trust policy so that only an OIDC token from your chosen project can assume that role. The trust policy determines under what conditions the role can be assumed.

To do this, go to an individual project’s page on CircleCI web app and navigate to Project Settings > Overview to find your Project ID.

Next, add the following condition to your role’s trust policy, so that only jobs in your chosen project can assume that role. Enter your Organization ID for ORGANIZATION_ID and your Project ID for PROJECT_ID.

This uses StringLike to match the sub claim of CircleCI’s OIDC token in your chosen project. Now, jobs in your other projects cannot assume this role.

The GCP configuration file can be set up using the GCP web UI. In the Workload Identity Federation UI, navigate to Grant Access, which will prompt the configuration, which can then be downloaded. You will need to create a file named CIRCLE_OIDC_TOKEN_FILE, which Google Cloud will read your identity token from (the file name can be anything, as long as it matches what is in the configuration under credential_source).

You will need your CircleCI organization ID, which can be found by navigating to Organization Settings > Overview on the CircleCI web app.

After navigating to the Grant Access section of the GCP web UI, follow these steps to add CircleCI as an external identity provider:

An example of the configuration file is shown below. Note, the audience has not been set up yet with the following:

In this configuration, credential_source will attempt to find your identity token in the CIRCLE_OIDC_TOKEN_FILE file.

If your token comes from an API response, it might be useful to set up the configuration to read a JSON file. In this case, the type will need to be set to json and you will need to provide a valid path, for example, response.id_token.

Please note, if needed, you can also attempt to generate the GCP configuration file by running the following script:

You will need to export the $CIRCLE_OIDC_TOKEN to the file named CIRCLE_OIDC_TOKEN_FILE by running the following:

You will also need to add the following environment variables to a context.

Below is a full example configuration adding GCP to a job and demonstrating that authentication works with the gcp-oidc-authenticate command. This example uses the circleci/gcp-cli orb.

You have the ability to use multiple service accounts from the same GCP project, or multiple service accounts from multiple GCP projects. You can read about these methods and find an example in CircleCI’s example repository.