Using OpenID Connect Tokens in Jobs
On This Page
In jobs using a context, CircleCI provides an OpenID Connect ID (OIDC) token in an environment variable. A job can use this to access compatible cloud services without a long-lived credential stored in CircleCI.
OpenID Connect ID token availability
In CircleCI jobs that use at least one context, the OpenID Connect ID token is available in the environment variable $CIRCLE_OIDC_TOKEN
.
Add a context to a job by adding the context
key to the workflows section of your circleci/config.yml
file:
workflows:
my-workflow:
jobs:
- run-tests:
context:
- my-context
Setting up your cloud service
Consult your cloud service’s documentation for how to add an identity provider. For example, AWS’s Creating OpenID Connect (OIDC) identity providers, or Google Cloud Platform’s Configuring workload identity federation.
The OpenID Provider is unique to your organization. The URL is https://oidc.circleci.com/org/ORGANIZATION_ID
, where ORGANIZATION_ID
is the organization ID (a universally unique identifier) that represents your organization. You can find your CircleCI organization ID by navigating to Organization Settings > Overview on the CircleCI web app.
The OpenID Connect ID tokens issued by CircleCI have a fixed audience (see aud
in the table below), which is also the organization ID.
Format of the OpenID Connect ID token
The OpenID Connect ID token contains the following standard claims:
Claims | Description |
---|---|
| The issuer. The issuer is specific to the CircleCI organization in which the job is being run. Its value is |
| The subject. This identifies who is running the CircleCI job and where. Its value is |
| The audience. Currently, this is a fixed value |
| The time of issuance. This is the time the token was created, which is shortly before the job starts. |
| The expiration time. Its value is one hour after the time of issuance. |
The OpenID Connect ID token also contains some additional claims with extra metadata about the job:
Additional claims | Metadata |
---|---|
| The ID of the project in which the job is running. Its value is a string containing a UUID identifying the CircleCI project. |
| An array of strings containing UUIDs that identify the context(s) used in the job. Currently, just one context is supported. |
Authenticate jobs with cloud providers
The following sections describe how to authenticate jobs on CircleCI with Amazon Web Services (AWS) and Google Cloud Platform (GCP).
AWS
The following AWS instructions are for:
-
A one-time configuration of your AWS account to trust CircleCI’s OIDC tokens
-
Running a job that uses the OIDC token to interact with AWS
Setting up AWS
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).
At this time, CircleCI’s built-in AWS Elastic Container Registry (ECR) authentication for pulling images does not support OIDC. |
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.
Adding AWS to the CircleCI configuration file
Now you are ready to choose the CircleCI jobs in your workflow that you want to receive an OpenID Connect token. Since the OpenID Connect token is only available to jobs that use at least one context, make sure each of the jobs you want to receive an OIDC token uses a context (the context may have no environment variables).
In your job, use the OpenID Connect token to do AWS STS’s AssumeRoleWithWebIdentity. Have the following information ready:
-
AWS region that you want to operate in
-
ARN of the IAM role that you created earlier
Here is an example config that uses the AWS CLI’s assume-role-with-web-identity subcommand to authenticate with AWS. It then performs a trivial interaction (aws sts get-caller-identity
) with AWS, demonstrating that authentication works. Replace that demonstration with whatever you want, such as uploading to an S3 bucket, pushing to ECR, or interacting with EKS.
version: 2.1
jobs:
deploy:
docker:
- image: amazon/aws-cli
environment:
AWS_DEFAULT_REGION: YOUR_AWS_REGION
AWS_ROLE_ARN: YOUR_ROLE_ARN
steps:
- run:
name: authenticate-and-interact
command: |
# use the OpenID Connect token to obtain AWS credentials
read -r AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN \<<< \
$(aws sts assume-role-with-web-identity \
--role-arn ${AWS_ROLE_ARN} \
--role-session-name "CircleCI-${CIRCLE_WORKFLOW_ID}-${CIRCLE_JOB}" \
--web-identity-token $CIRCLE_OIDC_TOKEN \
--duration-seconds 3600 \
--query 'Credentials.[AccessKeyId,SecretAccessKey,SessionToken]' \
--output text)
export AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN
# interact with AWS
aws sts get-caller-identity
Advanced Usage
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
.
"StringLike": {
"oidc.circleci.com/org/ORGANIZATION_ID:sub": "org/ORGANIZATION_ID/project/PROJECT_ID/user/*"
}
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.
Google Cloud Platform
The following GCP instructions are for:
-
A one-time configuration of your GCP settings to trust CircleCI’s OIDC tokens
-
Running a job that uses the OIDC token to interact with GCP
The Google Cloud CLI reads your configuration file, which contains necessary information instructing Google Cloud to authenticate. You can read about external identity providers on Google Cloud’s docs.
Setting up GCP
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:
-
Navigate to the IAM & Admin panel.
-
On the side panel, navigate to Workload Identity Federation.
-
Click the Add Provider button.
-
Select OpenID Connect (OIDC) from the "Select a provider" dropdown and click Save.
-
Fill out the Provider details form.
-
Select Allowed audiences since the
aud
claim in the JSON Web Token is a UUID (your CircleCI organization ID). Theaudience
will be your CircleCI organization ID. -
The issuer is
https://oidc.circleci.com/org/ORG_ID
, whereORG_ID
is your CircleCI organization ID.
-
-
Click Continue to configure provider attributes.
Configuring the provider attributes provides an opportunity to map claims in CircleCI’s Token to Google’s "understanding." For example:
google.subject
attribute.project_id
assertion.sub
assertion['oidc.circleci.com/project-id']
-
Navigate to Service Account in the IAM & Admin Panel to create a service account, and give appropriate permission.
-
Navigate back to Workload Identity Federation and select the provider from the table.
-
Click the Grant access button.
-
A modal will open and you will select the service account you created from the dropdown. This is the account that the token will impersonate, which grants all the associated permissions.
-
Under Select principals, you can add conditions, or leave the default.
-
Click Save. A pop-up will appear to ask you configure and download the configuration file. This file can also be downloaded later by navigating to Connected Service Accounts.
-
Save the downloaded configuration file in your repo. This file will be referenced in your CircleCI configuration.
An example of the configuration file is shown below. Note, the audience
has not been set up yet with the following:
-
PROJECT_NUMBER (the unique identifying number generated for your project)
-
POOL_ID (an ID that references the workload identity pool, for example
circleci_oidc
) -
PROVIDER_ID (an ID that references the workload identity pool provider, for example,
circleci
)
{
"type": "external_account",
"audience": "//iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID",
"subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
"token_url": "https://sts.googleapis.com/v1/token",
"service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/circleci-test@incubator-344312.iam.gserviceaccount.com:generateAccessToken",
"credential_source": {
"file": "CIRCLE_OIDC_TOKEN_FILE",
"format": {
"type": "text"
}
}
}
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
.
"credential_source": {
"file": "CIRCLE_OIDC_TOKEN_FILE",
"format": {
"type": "json",
"path": "response.id_token"
}
}
Please note, if needed, you can also attempt to generate the GCP configuration file by running the following script:
gcloud iam workload-identity-pools create-cred-config \
"${GCP_WORKLOAD_IDENTITY_POOL_AUDIENCE}" \
--output-file="${GCP_CREDENTIAL_CONFIGURATION_FILE}" \
--service-account="${GCP_SERVICE_ACCOUNT_EMAIL}" \
--credential-source-file="${GCP_CREDENTIAL_SOURCE_FILE}"
Adding GCP to the CircleCI configuration file
You will need to export the $CIRCLE_OIDC_TOKEN
to the file named CIRCLE_OIDC_TOKEN_FILE
by running the following:
echo $CIRCLE_OIDC_TOKEN >> CIRCLE_OIDC_TOKEN_FILE
You will also need to add the following environment variables to a context.
Context var name | Example value | Notes |
GCP_PROJECT_ID |
| |
GCP_WIP_ID |
| |
GCP_WIP_PROVIDER_ID |
| |
GCP_SERVICE_ACCOUNT_EMAIL |
|
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 the circleci/gcp-cli orb.
version: 2.1
orbs:
gcp-cli: circleci/gcp-cli@2.4.1
commands:
gcp-oidc-generate-cred-config-file:
description: "Authenticate with GCP using a CircleCI OIDC token."
parameters:
project_id:
type: env_var_name
default: GCP_PROJECT_ID
workload_identity_pool_id:
type: env_var_name
default: GCP_WIP_ID
workload_identity_pool_provider_id:
type: env_var_name
default: GCP_WIP_PROVIDER_ID
service_account_email:
type: env_var_name
default: GCP_SERVICE_ACCOUNT_EMAIL
gcp_cred_config_file_path:
type: string
default: /home/circleci/gcp_cred_config.json
oidc_token_file_path:
type: string
default: /home/circleci/oidc_token.json
steps:
- run:
command: |
# Store OIDC token in temp file
echo $CIRCLE_OIDC_TOKEN > << parameters.oidc_token_file_path >>
# Create a credential configuration for the generated OIDC ID Token
gcloud iam workload-identity-pools create-cred-config \
"projects/${<< parameters.project_id >>}/locations/global/workloadIdentityPools/${<< parameters.workload_identity_pool_id >>}/providers/${<< parameters.workload_identity_pool_provider_id >>}"\
--output-file="<< parameters.gcp_cred_config_file_path >>" \
--service-account="${<< parameters.service_account_email >>}" \
--credential-source-file=<< parameters.oidc_token_file_path >>
gcp-oidc-authenticate:
description: "Authenticate with GCP using a GCP credentials file."
parameters:
gcp_cred_config_file_path:
type: string
default: /home/circleci/gcp_cred_config.json
steps:
- run:
command: |
# Configure gcloud to leverage the generated credential configuration
gcloud auth login --brief --cred-file "<< parameters.gcp_cred_config_file_path >>"
# Configure ADC
echo "export GOOGLE_APPLICATION_CREDENTIALS='<< parameters.gcp_cred_config_file_path >>'" | tee -a $BASH_ENV
jobs:
gcp-oidc-defaults:
executor: gcp-cli/default
steps:
- gcp-cli/install
- gcp-oidc-generate-cred-config-file
- gcp-oidc-authenticate
- run:
name: Verify that gcloud is authenticated
environment:
GCP_SERVICE_ACCOUNT_EMAIL: jennings-oidc-test@makoto-workbench.iam.gserviceaccount.com
command: gcloud iam service-accounts get-iam-policy "${GCP_SERVICE_ACCOUNT_EMAIL}"
workflows:
main:
jobs:
- gcp-oidc-defaults:
name: Generate Creds File and Authenticate
context:
- gcp-oidc-dev
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.
Help make this document better
This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.
- Suggest an edit to this page (please read the contributing guidefirst).
- To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
- CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.
Need support?
Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.
You can also visit our support site to find support articles, community forums, and training resources.
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.