> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manual OIDC token exchange for Object Storage

> Manually configure OIDC Workload Identity Federation to authenticate CKS workloads to CoreWeave AI Object Storage

This guide describes how to manually configure OpenID Connect (OIDC) Workload Identity Federation between a CoreWeave Kubernetes Service (CKS) cluster and CoreWeave AI Object Storage. This configuration lets CKS workloads authenticate to Object Storage without long-lived static credentials. The resulting Pod receives a projected service account token that it exchanges for temporary S3 credentials at runtime.

You can do this automatically with minimal configuration by installing the [Pod Identity Webhook](https://docs.coreweave.com/security/tutorials/cks-object-storage-authentication/automatic.md). When you need full control over the token exchange or need to debug it, use this guide.

## Prerequisites

Before you begin, make sure you have the following in place.

In your CoreWeave organization, you must have:

* A deployed [CKS cluster with OIDC Workload Identity enabled](https://docs.coreweave.com/products/cks/auth-access/workload-identity/introduction.md).

The following table separates roles that cover the administrative tasks from the narrower permissions used by this guide:

| Task | Role that covers the task | Granular permissions |
| - | - | - |
| Create or manage the CKS cluster | **CKS Admin** | After the cluster exists, Kubernetes RBAC controls whether you can create the guide's ServiceAccount and Pods. |
| Create the OIDC Workload Federation configuration | **IAM Admin** | CoreWeave IAM Access Policies assign roles rather than individual IAM actions. |
| Create and view the Object Storage organization access policy | **Object Storage Admin** | `cwobject:EnsureAccessPolicy` and `cwobject:ListAccessPolicy` granted to your user through an existing organization access policy. Add `cwobject:DeleteAccessPolicy` if you must delete the policy. |
| Exchange the ServiceAccount token and run the verification command | No CoreWeave IAM role applies to the federated ServiceAccount. | Grant `cwobject:CreateAccessKeyOIDC` and `s3:ListAllMyBuckets` to the WIF principal in an Object Storage organization access policy, with `resources: ["*"]`. |

An Object Storage Admin must create the first organization access policy that delegates granular `cwobject:` permissions. The **Object Storage Admin** role governs the Object Storage control plane; it doesn't grant S3 data access.

In your local environment, you must have:

* A terminal. This tutorial is written for bash and zsh.
* [`kubectl`](https://kubernetes.io/docs/reference/kubectl/) installed and accessible from your terminal path.
* An S3 command-line interface (CLI) client installed and accessible from your terminal path. This guide uses the [AWS CLI](https://aws.amazon.com/cli/). If you use another S3 CLI, adapt the commands as needed.

## Configure the CKS OIDC provider

Register your CKS cluster as a trusted OIDC identity provider for Object Storage. This lets Pods running in the cluster exchange their projected service account tokens for temporary S3 credentials.

1. Launch your CKS cluster.

2. In the Cloud Console, retrieve the **OIDC Issuer URL** of your CKS cluster:
   * Go to the [Clusters](https://console.coreweave.com/clusters) page.
   * Click the name of your cluster. A cluster details panel opens on the right.
   * In the **Cluster access** section, copy the **OIDC Issuer URL**.

3. Configure OIDC Workload Identity Federation in the Cloud Console using this OIDC Issuer URL.

4. On the [Workload Federation](https://console.coreweave.com/organization/iam/workload-federation/oidc) page, create a new OIDC configuration.
   * Click **Create OIDC configuration**. The configuration form opens.
   * Set the configuration name (choose a name that indicates it is for federating CKS tokens with AI Object Storage).
   * Enter the CKS cluster's OIDC Issuer URL that you copied earlier into the **Issuer URL** field.
   * Set the **Client ID (Audience)** field to `https://coreweave.com/iam` (recommended) or choose another audience.
   * Click **Create** to save the configuration.

## Configure `kubectl` and create a Kubernetes ServiceAccount

1. Download a kubeconfig for your CKS cluster using one of the following methods:

   * **Get a kubeconfig for an existing cluster**: Go to the [Clusters](https://console.coreweave.com/clusters) page. Find the cluster, click the vertical ellipsis next to its name, and then click **Get kubeconfig**.
   * **Create an API access token and kubeconfig**: Go to the [Tokens](https://console.coreweave.com/tokens) page, and click **Create Token**. Store your token secret securely, set the context by selecting your existing cluster, and then click **Download** to get the kubeconfig.

   Save the kubeconfig file to your local machine.

2. To let `kubectl` locate the kubeconfig that you downloaded, export an environment variable. Replace `[PATH-TO-KUBECONFIG-FILE]` with the path to the downloaded file:

   ```bash theme={"system"}
   export KUBECONFIG=[PATH-TO-KUBECONFIG-FILE]
   ```

3. Test that your `kubectl` installation works:

   ```bash theme={"system"}
   kubectl config get-contexts
   kubectl get nodes
   ```

   If the environment variable is set, the downloaded context appears. If the cluster has a ready Node Pool, `kubectl get nodes` also shows its Nodes.

4. Create a Kubernetes ServiceAccount by saving the following data to a file named `test-service-account.yaml`:

   ```yaml title="test-service-account.yaml" theme={"system"}
   apiVersion: v1
   kind: ServiceAccount
   metadata:
     name: test-service-account
     namespace: default
   ```

5. Create the account:

   ```bash theme={"system"}
   kubectl apply -f test-service-account.yaml
   ```

6. Verify the account:

   ```bash theme={"system"}
   kubectl get serviceaccounts
   ```

   If successful, `test-service-account` is visible.

## Grant the service account access to Object Storage

You must grant the service account's federated identity access to Object Storage through an organization access policy. Use the OIDC Issuer URL you copied earlier and the service account name to construct the workload identity federation (WIF) principal. Replace `[OIDC-ISSUER-URL]` with the OIDC Issuer URL from your cluster's details panel:

```text theme={"system"}
role/[OIDC-ISSUER-URL]:system:serviceaccount:default:test-service-account
```

The verification Pod requires only `cwobject:CreateAccessKeyOIDC` to exchange its OIDC token and `s3:ListAllMyBuckets` to run `aws s3api list-buckets`. Both are global actions and require `resources: ["*"]`. For a production workload, replace `s3:ListAllMyBuckets` with the specific S3 actions and bucket resources that the workload needs.

The following example policy grants only the actions required by the verification Pod:

```json theme={"system"}
{
  "policy": {
    "version": "v1alpha1",
    "name": "wif-service-account-access",
    "statements": [
      {
        "name": "allow-s3-access-for-cks-workload",
        "effect": "Allow",
        "actions": ["cwobject:CreateAccessKeyOIDC", "s3:ListAllMyBuckets"],
        "resources": ["*"],
        "principals": ["role/[OIDC-ISSUER-URL]:system:serviceaccount:default:test-service-account"]
      }
    ]
  }
}
```

Create this policy with the Cloud Console, the [CoreWeave Terraform Provider](https://registry.terraform.io/providers/coreweave/coreweave/latest/docs/resources/object_storage_organization_access_policy), or the Object Storage API. Before you deploy your workload, replace `s3:ListAllMyBuckets` with its required S3 actions and resources. For examples, see [Organization access policy examples](https://docs.coreweave.com/products/storage/object-storage/auth-access/organization-policies/examples.md).

## Set up the workload

With the service account created and granted access, reference it from your Object Storage policies and from your workload Pod.

* You can define Object Storage policies that reference a role of the form `[ISSUER]:[SUBJECT]`, where the issuer is discovered through the well-known URL and the subject follows a standard pattern for Kubernetes service accounts, based on namespace and service account name.
* You can get the OIDC well-known URL from the Cloud Console. On the **Clusters** page, select your cluster, and then copy the OIDC Issuer URL.

When you create Object Storage organization and bucket policies for the service account, use the following principal syntax:

| Principal type | Syntax |
| - | - |
| Principal | `[OIDC-ISSUER-URL]:system:serviceaccount:default:test-service-account` |
| Organization policy `"principals"` | `["role/[OIDC-ISSUER-URL]:system:serviceaccount:default:test-service-account"]` |
| Bucket policy `"Principal"` | `{"AWS": "arn:aws:iam::[ORG-ID]:role/[OIDC-ISSUER-URL]:system:serviceaccount:default:test-service-account"}` |

## Create the workload Pod

Create a Pod manifest that mounts a projected service account token with the correct audience. The Pod uses this token to exchange for temporary Object Storage credentials at runtime.

Replace `[ORG-ID]` with your CoreWeave organization ID and replace `[CONTAINER-IMAGE]` with your application's container image:

To work with AI Object Storage, configure your Pod's S3 endpoints to use virtual addressing style and set the appropriate endpoint URL.

> [accordion] Configure S3 endpoints for Pods
>
> Because the environment variables handle credential exchange, you only need to configure the S3 endpoint and addressing style in your application. For example, with the AWS CLI:
>
> ```bash theme={"system"}
> aws configure set s3.addressing_style virtual
> aws configure set endpoint_url "http://cwlota.com"
> ```
>
> Alternatively, you can mount this configuration file into the container from a ConfigMap and set the `AWS_CONFIG_FILE` variable to the location of the mounted file.
>
> ```ini theme={"system"}
> [default]
> s3 =
>     addressing_style = virtual
> endpoint_url = http://cwlota.com
> ```
>
> When your workloads run inside a CKS cluster, use the LOTA endpoint (`cwlota.com`) for optimal performance. For more configuration options (Boto3, s3cmd, Multi-Storage Client), see [Attaching endpoints](https://docs.coreweave.com/products/storage/object-storage/using-object-storage/configure-endpoints.md#full-configuration-examples).

```yaml title="workload-pod.yaml" theme={"system"}
apiVersion: v1
kind: Pod
metadata:
  name: my-workload
  namespace: default
spec:
  serviceAccountName: test-service-account
  containers:
  - name: app
    image: "[CONTAINER-IMAGE]"
    env:
    - name: AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE
      value: /var/run/secrets/tokens/oidc-token
    - name: AWS_CONTAINER_CREDENTIALS_FULL_URI
      value: "https://api.coreweave.com/v1/cwobject/temporary-credentials/oidc/[ORG-ID]"
    - name: AWS_DEFAULT_REGION
      value: "US-EAST-04A"
    volumeMounts:
    - name: oidc-token
      mountPath: /var/run/secrets/tokens
      readOnly: true
  volumes:
  - name: oidc-token
    projected:
      sources:
      - serviceAccountToken:
          path: oidc-token
          audience: "https://coreweave.com/iam"   # Or a custom audience
          expirationSeconds: 3600
```

* Apply the manifest:

  ```bash theme={"system"}
  kubectl apply -f workload-pod.yaml
  ```

The Pod mounts the projected token at `/var/run/secrets/tokens/oidc-token`. Supported versions of AWS software development kits (SDKs) and the AWS CLI use two environment variables: `AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE` and `AWS_CONTAINER_CREDENTIALS_FULL_URI`. The software uses these variables to exchange the OIDC token for temporary S3 credentials. Kubernetes rotates the projected OIDC token according to its time to live, and the AWS credential provider refreshes the temporary S3 credentials before they expire.

## Optional: Verify the setup

To confirm the projected token exchange works before you deploy your real workload, create a test Pod that uses the `amazon/aws-cli:2.33.2` image:

```yaml title="test-manual-pod.yaml" theme={"system"}
apiVersion: v1
kind: Pod
metadata:
  name: test-manual-oidc
  namespace: default
spec:
  restartPolicy: Never
  serviceAccountName: test-service-account
  containers:
  - name: test
    image: amazon/aws-cli:2.33.2
    command:
    - sh
    - -c
    - |
        aws configure set s3.addressing_style virtual
        aws configure set endpoint_url http://cwlota.com
        aws s3api list-buckets
    env:
    - name: AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE
      value: /var/run/secrets/tokens/oidc-token
    - name: AWS_CONTAINER_CREDENTIALS_FULL_URI
      value: "https://api.coreweave.com/v1/cwobject/temporary-credentials/oidc/[ORG-ID]"
    - name: AWS_DEFAULT_REGION
      value: "US-EAST-04A"
    volumeMounts:
    - name: oidc-token
      mountPath: /var/run/secrets/tokens
      readOnly: true
  volumes:
  - name: oidc-token
    projected:
      sources:
      - serviceAccountToken:
          path: oidc-token
          audience: "https://coreweave.com/iam"   # Or a custom audience
          expirationSeconds: 3600
```

1. Apply the test Pod:

   ```bash theme={"system"}
   kubectl apply -f test-manual-pod.yaml
   ```

2. Check the Pod logs for the response:

   ```bash theme={"system"}
   kubectl logs test-manual-oidc
   ```

   When your OIDC configuration and access policies are configured correctly, the logs contain a JSON response that lists your buckets. If you see an `AccessDenied` error, verify the organization policy. It must grant `cwobject:CreateAccessKeyOIDC` and `s3:ListAllMyBuckets` to the correct WIF principal with `resources: ["*"]`.

3. Clean up the test Pod:

   ```bash theme={"system"}
   kubectl delete pod test-manual-oidc
   ```

## Optional: Validate locally

You can also validate the OIDC token exchange from your local machine, outside a Kubernetes Pod. Create a service account token and call the credential endpoint directly. For one-time testing and debugging, this approach isolates the credential exchange from the rest of your workload.

You need the following additional tools for local validation:

* `curl` for calling the credential endpoint.
* `jq` for parsing JSON responses.
* [jwt.io](https://www.jwt.io/) (optional) for inspecting OIDC token contents.

### Test that the service account token can authenticate

Create a service account token with the same audience as your WIF configuration and exchange it for temporary Object Storage credentials. The following example uses the recommended audience, `https://coreweave.com/iam`. In the command, replace `[ORG-ID]` with your CoreWeave organization ID:

```bash theme={"system"}
OIDC_TOKEN=$(kubectl create token -n default test-service-account --audience=https://coreweave.com/iam)
printf 'header = "Authorization: %s"\n' "$OIDC_TOKEN" | curl --config - \
  "https://api.coreweave.com/v1/cwobject/temporary-credentials/oidc/[ORG-ID]" | jq

unset OIDC_TOKEN
```

If authentication succeeds, you see a response similar to the following:

```json theme={"system"}
{
  "AccessKeyId": "CWAKIAEXAMPLE1234567",
  "SecretAccessKey": "wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY",
  "Token": "",
  "Expiration": "2026-03-14T21:44:43Z",
  "attributes": {
    "cw-role": "https://oidc.example.coreweave.com/abc123:system:serviceaccount:default:test-service-account"
  }
}
```

### Test access with the AWS CLI

Configure a local AWS CLI profile that uses a credential process to fetch temporary credentials. To use the [CoreWeave Intelligent CLI](https://github.com/coreweave/cwic) (`cwic`) instead of a custom script, see [Share credentials across processes](https://docs.coreweave.com/products/storage/object-storage/using-object-storage/share-credentials-across-processes.md#exchange-an-oidc-token). The Kubernetes Pod example on that page uses the same projected token this tutorial sets up.

To use a custom script, replace `[CREDENTIAL-SCRIPT-PATH]` with the path to your credential script (for example, `/bin/cw-auth.sh`). The script must obtain a service account token, exchange it at the credential endpoint, and return JSON in the format the AWS CLI expects. For a full walkthrough of writing this script, see [Workload Identity Federation with a credential process](https://docs.coreweave.com/products/storage/object-storage/using-object-storage/s3-clients/aws.md#workload-identity-federation-with-a-credential-process).

The following commands set the virtual addressing style, the credential process, the region, and the endpoint URL in a new profile called `cw-test`:

```bash theme={"system"}
export AWS_CONTAINER_AUTHORIZATION_TOKEN=$(kubectl create token -n default test-service-account --audience=https://coreweave.com/iam)
export AWS_CONTAINER_CREDENTIALS_FULL_URI="https://api.coreweave.com/v1/cwobject/temporary-credentials/oidc/[ORG-ID]"

aws configure set s3.addressing_style virtual --profile cw-test
aws configure set credential_process "[CREDENTIAL-SCRIPT-PATH]" --profile cw-test
aws configure set region "US-EAST-04A" --profile cw-test
aws configure set endpoint_url "https://cwobject.com" --profile cw-test
```

> [!NOTE]
>
> Use the primary endpoint (`https://cwobject.com`) for local testing because the LOTA endpoint (`http://cwlota.com`) is accessible only from within CoreWeave clusters.

Run an S3 command to verify the credential exchange works:

```bash theme={"system"}
aws s3api list-buckets --profile cw-test
```

If the credential exchange succeeds, the command lists the buckets that the federated identity can access.

## Next steps

After you validate the setup, consider the following options:

* To use automatic authentication when you don't need manual control, see [Automatic authentication with the Pod Identity Webhook](https://docs.coreweave.com/security/tutorials/cks-object-storage-authentication/automatic.md).
* To review the CKS configuration, see [OIDC Workload Identity for CKS](https://docs.coreweave.com/products/cks/auth-access/workload-identity/introduction.md).
* Review [Workload Identity Federation for Object Storage](https://docs.coreweave.com/products/storage/object-storage/auth-access/workload-identity-federation/use-oidc-tokens.md).
