---
title: "OIDC tokens with custom claims"
description: "Create CircleCI OIDC tokens with the environment CLI and customize the aud claim to connect your jobs to different cloud services without long-lived secrets."
platform: "Cloud, Server"
doc_version: "Server"
last_updated: "2026-10-26"
---

> For current CircleCI product defaults, deprecated patterns, and Cloud/Server differences, see [AGENTS.md](https://circleci.com/docs/AGENTS.md).
>
> For the complete documentation index and site structure, see [llms.txt](https://circleci.com/docs/llms.txt).

# OIDC tokens with custom claims

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

For more information on OIDC tokens, see the [OpenID Connect Tokens](https://circleci.com/docs/guides/server/permissions-authentication/openid-connect-tokens/) overview.

## Create OIDC token with root issuer

Use the `--root-issuer` flag with the CircleCI environment CLI to generate an OIDC token with the issuer (`iss`) claim set to `https://oidc.circleci.com`.

## Create OIDC token in a job with custom claims

See also the full [Environment CLI Usage Guide](https://circleci.com/docs/reference/environment-cli-usage-guide/).

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 environment CLI in a `step` to create your customized token, as follows:

```shell
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.

**OIDC tokens** created using this method can be printed with no masking. Take care to not log/print the token in your job steps.

### Set the audience with the aud flag

Use the `--aud` flag as a shorter way to set the `aud` claim.

```shell
circleci run oidc get --aud audience_name
```

You cannot combine `--aud` with `--claims`.

## 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.

```yaml
version: 2.1

commands:
  install-awscli: # https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2-linux.html
    steps:
      - run:
          name: Install awscli
          working_directory: /tmp/awscli
          command: |
            curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
            unzip awscliv2.zip
            ./aws/install
            echo 'export AWS_PAGER=""' | tee -a $BASH_ENV

jobs:
  deploy-to-s3:
    docker:
      - image: node:current-bullseye
    environment:
      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
    steps:
      - 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
            echo $OIDC_TOKEN > "$AWS_WEB_IDENTITY_TOKEN_FILE"
            # 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

workflows:
  build-and-deploy:
    jobs:
      - deploy-to-s3
```