Start Building for Free

OIDC tokens with custom claims

5 months ago1 min read
Server v4.4+
On This Page

Use OpenID Connect (OIDC) tokens to connect your pipelines to compatible cloud services without the need to manage long-lived secrets in CircleCI. Create CircleCI OIDC tokens, using the CircleCI CLI, and customize the aud claim to meet the unique needs of different cloud services.

For more information on OIDC token, see the OpenID Connect tokens overview.

Create OIDC token in a job with custom claims

CircleCI allows you to create OIDC tokens in a job. Using this method you can:

  • Customize the aud claim. Only the aud claim is customizable.

  • Create one or more OIDC tokens in a job.

Use the CircleCI CLI in a step to create your customized token, as follows:

circleci run oidc get --claims '{"aud": "audience_name"}'

The above command creates an OIDC token with the aud claim set to audience_name, and returns the token to stdout. Pass this value to a variable and use the variable to call a cloud service for authentication.

Example configuration

This example configuration deploys a static HTML webpage to AWS S3 using an OIDC token, with a customized aud claim, in a job.

version: 2.1

  install-awscli: #
      - run:
          name: Install awscli
          working_directory: /tmp/awscli
          command: |
            curl "" -o ""
            echo 'export AWS_PAGER=""' | tee -a $BASH_ENV

      - image: node:current-bullseye
      AWS_DEFAULT_REGION: us-east-1
      AWS_ROLE_ARN: "arn:aws:iam::123456789012:role/S3-READ-WRITE-OIDC-ROLE"
      S3_TARGET: s3://test-app-oidc-token-test-bucket
      - checkout
      - install-awscli
      - run:
          name: Deploy to S3
          command: |
            # set the variable AWS_WEB_IDENTITY_TOKEN_FILE to a temporary file that will hold the OIDC token
            export AWS_WEB_IDENTITY_TOKEN_FILE="$(mktemp -u)"
            # create OIDC token with customized aud claim of org-id
            OIDC_TOKEN=$(circleci run oidc get --claims '{"aud": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}')
            # copy the OIDC token to the AWS_WEB_IDENTITY_TOKEN_FILE created earlier
            # make AWS cli calls
            aws sts get-caller-identity
            # copy the index.html file of the static site to the specified S3_TARGET location
            aws s3 cp ./index.html $S3_TARGET

      - deploy-to-s3

Suggest an edit to this page

Make a contribution
Learn how to contribute