OpenID Connect (OIDC) authentication

Use short-lived OIDC tokens to securely authenticate to cloud resources

OpenID Connect (OIDC) lets your Baseten deployments authenticate to cloud resources like S3 buckets and container registries using short-lived tokens instead of long-lived credentials.

Without OIDC, accessing cloud resources requires long-lived credentials: static API keys or service account keys stored as secrets in Baseten. These keys don’t expire on their own, so if they’re leaked or forgotten, they remain valid until someone manually rotates them. You’re responsible for tracking which keys exist, where they’re used, and when to rotate them.

OIDC takes a different approach. Instead of static keys, Baseten issues short-lived tokens scoped to a specific deployment. There are no secrets to store, rotate, or clean up.

Baseten OIDC currently supports:

• AWS: Amazon ECR (container images) and Amazon S3 (model weights)
• Google Cloud: Artifact Registry, GCR (container images), and Google Cloud Storage (model weights)

How Baseten OIDC works

Baseten acts as an OIDC identity provider with the following configuration:

• Issuer: https://oidc.baseten.co
• Audience: oidc.baseten.co

When you deploy your model, Baseten generates short-lived OIDC tokens that identify your specific workload. Your cloud provider validates these tokens against the trust relationship you configure, then grants access to the specified resources.

Token structure

Each OIDC token includes standard JWT claims and custom claims that identify the workload. Here’s an example unsigned payload:

{
  "iss": "https://oidc.baseten.co",
  "sub": "v=1:org=Mvg9jrRd:team=AviIZ0y3:model=kW9wuKFN:deployment=e5f6g7h8:environment=production:type=model_container",
  "aud": "oidc.baseten.co",
  "iat": 1700000000,
  "exp": 1700003600,
  "jti": "550e8400-e29b-41d4-a716-446655440000",
  "org": "Mvg9jrRd",
  "team": "AviIZ0y3",
  "model": "kW9wuKFN",
  "deployment": "e5f6g7h8",
  "environment": "production",
  "type": "model_container"
}

The sub claim uses a structured format that encodes the workload identity:

v=1:org={org_id}:team={team_id}:model={model_id}:deployment={deployment_id}:environment={environment}:type={workload_type}

Claim components

Component	Description	Example
org	Your organization ID	Mvg9jrRd
team	Team ID within your organization	AviIZ0y3
model	Model ID	kW9wuKFN
deployment	Specific deployment/version ID	e5f6g7h8
environment	User-defined environment name (max 40 characters). Defaults to <none> if not set	production
type	Workload type: model_build or model_container	model_build

Workload types

• model_build: Token used during model image building (for example, pulling base images from ECR/GCR).
• model_container: Token used by running model containers (for example, downloading weights from S3/GCS).

Subject claim patterns

Common patterns for scoping which workloads can access your resources:

• AWS: Use these in the IAM role trust policy under Condition.StringLike for oidc.baseten.co:sub. Wildcards (*) are supported.
• GCP: Use these in the Workload Identity Provider attribute-condition. With the mapping google.subject=assertion.sub (see Create a Workload Identity Provider), reference the sub claim as google.subject. GCP does not support wildcards; use startsWith() (and contains() where needed).

All workloads in a team

To give every workload in your team access to a resource, match on the team ID with a wildcard for everything else.

AWS (trust policy)

v=1:org=Mvg9jrRd:team=AviIZ0y3:*

GCP (attribute-condition)

google.subject.startsWith('v=1:org=Mvg9jrRd:team=AviIZ0y3:')

Specific model, all deployments

To restrict access to a single model while allowing all of its deployments and environments, match on the model ID.

AWS (trust policy)

v=1:org=Mvg9jrRd:team=AviIZ0y3:model=kW9wuKFN:*

GCP (attribute-condition)

google.subject.startsWith('v=1:org=Mvg9jrRd:team=AviIZ0y3:model=kW9wuKFN:')

Specific environment, all models

To scope access by environment, match workloads deployed to a specific environment like production.

AWS (trust policy)

v=1:org=Mvg9jrRd:team=AviIZ0y3:*:environment=production:*

GCP (attribute-condition)

google.subject.startsWith('v=1:org=Mvg9jrRd:team=AviIZ0y3:') && google.subject.contains('environment=production')

Build-time only access

To limit access to the build phase, like pulling base images from a private registry, match on the model_build workload type.

AWS (trust policy)

v=1:org=Mvg9jrRd:team=AviIZ0y3:*:type=model_build

GCP (attribute-condition)

google.subject.startsWith('v=1:org=Mvg9jrRd:team=AviIZ0y3:') && google.subject.endsWith('type=model_build')

Runtime only access

To limit access to running containers, like downloading model weights, match on the model_container workload type.

AWS (trust policy)

v=1:org=Mvg9jrRd:team=AviIZ0y3:*:type=model_container

GCP (attribute-condition)

google.subject.startsWith('v=1:org=Mvg9jrRd:team=AviIZ0y3:') && google.subject.endsWith('type=model_container')

Specific model and environment

To apply the most restrictive access, combine model and environment matching so only a specific model in a specific environment can authenticate.

AWS (trust policy)

v=1:org=Mvg9jrRd:team=AviIZ0y3:model=kW9wuKFN:*:environment=production:*

GCP (attribute-condition)

google.subject.startsWith('v=1:org=Mvg9jrRd:team=AviIZ0y3:model=kW9wuKFN:') && google.subject.contains('environment=production')

Finding your OIDC identifiers

Use truss whoami --show-oidc to view your organization and team IDs, issuer, audience, and subject claim format needed for configuring cloud provider trust policies.

Cloud provider setup

AWS

Provision all resources with a single script

Run this script to create the OIDC provider, IAM role, and permission policies. Set the variables at the top, then execute the entire script.

Prerequisites

• AWS CLI 2.x.
• Bash 3.2+.
• AWS credentials configured for the target account (aws configure, environment variables, or an IAM role) with permission to create OIDC identity providers, IAM roles, and inline role policies (for example iam:CreateOpenIDConnectProvider, iam:CreateRole, iam:PutRolePolicy).

Review each variable before running. Replace the empty values with your actual AWS account ID, S3 bucket name, organization ID, and team ID.

#!/usr/bin/env bash
set -euo pipefail

require_non_empty() {
  local _name="$1"
  local _desc="${2:-$1}"
  local _val
  eval "_val=\${${_name}-}"
  if [ -z "$_val" ]; then
    echo "error: ${_desc} is empty; set ${_name} in the configuration section." >&2
    exit 1
  fi
}

# ──────────────────────────────────────────────
# Configuration — replace these with your values
# ──────────────────────────────────────────────
AWS_ACCOUNT_ID=""             # Your AWS account ID
S3_BUCKET=""                  # S3 bucket for model weights
ROLE_NAME="BasetenOIDCRole"   # IAM role name
BASETEN_ORG_ID=""             # From `truss whoami --show-oidc`
BASETEN_TEAM_ID=""            # From `truss whoami --show-oidc`

require_non_empty AWS_ACCOUNT_ID "AWS account ID"
require_non_empty S3_BUCKET "S3 bucket name (model weights)"
require_non_empty BASETEN_ORG_ID "Baseten organization ID"
require_non_empty BASETEN_TEAM_ID "Baseten team ID"
require_non_empty ROLE_NAME "IAM role name"

OIDC_ISSUER="oidc.baseten.co"
OIDC_ISSUER_URL="https://${OIDC_ISSUER}"

# ──────────────────────────────────
# 1. Create the OIDC identity provider
# ──────────────────────────────────
echo "Creating OIDC identity provider..."

if ! output=$(aws iam create-open-id-connect-provider \
  --url "${OIDC_ISSUER_URL}" 2>&1); then
  if [[ "$output" == *"EntityAlreadyExists"* ]]; then
    echo "OIDC provider already exists, continuing..."
  else
    echo "$output" >&2
    exit 1
  fi
else
  echo "OIDC provider created."
fi

# ──────────────────────────────────
# 2. Create the IAM trust policy
# ──────────────────────────────────
TRUST_POLICY=$(cat <<EOF
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::${AWS_ACCOUNT_ID}:oidc-provider/${OIDC_ISSUER}"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "${OIDC_ISSUER}:aud": "${OIDC_ISSUER}"
        },
        "StringLike": {
          "${OIDC_ISSUER}:sub": "v=1:org=${BASETEN_ORG_ID}:team=${BASETEN_TEAM_ID}:*"
        }
      }
    }
  ]
}
EOF
)

# ──────────────────────────────────
# 3. Create the IAM role
# ──────────────────────────────────
echo "Creating IAM role ${ROLE_NAME}..."
aws iam create-role \
  --role-name "${ROLE_NAME}" \
  --assume-role-policy-document "${TRUST_POLICY}" \
  --description "Baseten OIDC role for model workloads"

echo "IAM role created."

# ──────────────────────────────────
# 4. Attach ECR read policy
# ──────────────────────────────────
ECR_POLICY=$(cat <<EOF
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ecr:GetAuthorizationToken",
        "ecr:BatchCheckLayerAvailability",
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchGetImage"
      ],
      "Resource": "*"
    }
  ]
}
EOF
)

echo "Attaching ECR read policy..."
aws iam put-role-policy \
  --role-name "${ROLE_NAME}" \
  --policy-name "BasetenECRReadAccess" \
  --policy-document "${ECR_POLICY}"

# ──────────────────────────────────
# 5. Attach S3 read policy
# ──────────────────────────────────
S3_POLICY=$(cat <<EOF
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::${S3_BUCKET}",
        "arn:aws:s3:::${S3_BUCKET}/*"
      ]
    }
  ]
}
EOF
)

echo "Attaching S3 read policy..."
aws iam put-role-policy \
  --role-name "${ROLE_NAME}" \
  --policy-name "BasetenS3ReadAccess" \
  --policy-document "${S3_POLICY}"

# ──────────────────────────────────
# Done
# ──────────────────────────────────
ROLE_ARN="arn:aws:iam::${AWS_ACCOUNT_ID}:role/${ROLE_NAME}"
echo ""
echo "Setup complete. IAM role ARN:"
echo "  ${ROLE_ARN}"
echo ""
echo "Use this role ARN in your Truss configuration."

This creates a single role with both ECR and S3 permissions. If you only need ECR or S3 access (not both), comment out or remove the policy section you don’t need (step 4 or step 5).

If you prefer to walk through each step manually, or need to customize individual resources, follow the instructions below.

Create an OIDC identity provider

Register Baseten as a trusted OIDC provider in your AWS account.

1. Navigate to the AWS IAM Console.
2. Go to Identity providers → Add provider.
3. Select OpenID Connect.
4. Configure the provider:
   • Provider URL: https://oidc.baseten.co
   • Click Get thumbprint to verify the provider.
   • Audience: oidc.baseten.co
5. Click Add provider.

If your AWS account requires sts.amazonaws.com as a trusted audience, add it to the OIDC provider first, then add oidc.baseten.co as an additional audience.

Create an IAM role

Create a role that your Baseten workloads can assume via OIDC.

1. Go to Roles → Create role.
2. Select Web identity as the trusted entity type.
3. Choose the OIDC provider you created.
4. Select Audience: oidc.baseten.co, then click Next.
5. On the next page, attach permissions policies for the resources your models need to access:

ECR access (for base images)

Attach this policy to allow pulling container images from ECR.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ecr:GetAuthorizationToken",
        "ecr:BatchCheckLayerAvailability",
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchGetImage"
      ],
      "Resource": "*"
    }
  ]
}

S3 access (for model weights)

Attach this policy to allow reading model weights from S3.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::my-model-weights-bucket",
        "arn:aws:s3:::my-model-weights-bucket/*"
      ]
    }
  ]
}

6. Configure the trust policy: Edit the role’s trust policy to include subject claim conditions. After creating the role, go to the role → Trust relationships → Edit and use a policy like this:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::<aws-account-id>:oidc-provider/oidc.baseten.co"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "oidc.baseten.co:aud": "oidc.baseten.co"
        },
        "StringLike": {
          "oidc.baseten.co:sub": "v=1:org=Mvg9jrRd:team=AviIZ0y3:*"
        }
      }
    }
  ]
}

Replace <aws-account-id> with your AWS account ID, and adjust the sub claim pattern to match your security requirements.

GCP

Provision all resources with a single script

Run this script to create the service account, Workload Identity Pool, provider, and role bindings. Set the variables at the top, then execute the entire script.

Prerequisites

• Google Cloud SDK (gcloud) 390.0.0+.
• Bash 3.2+.
• gcloud authenticated (gcloud auth login and application-default credentials if needed) with permission to create service accounts, Workload Identity Pools and providers, and modify project IAM (for example Service Account Admin, Workload Identity Pool Admin, and Project IAM Admin or a custom role with equivalent actions on the target project).

Review each variable before running. Replace the empty values with your actual GCP project ID, project number, organization ID, and team ID.

#!/usr/bin/env bash
set -euo pipefail

require_non_empty() {
  local _name="$1"
  local _desc="${2:-$1}"
  local _val
  eval "_val=\${${_name}-}"
  if [ -z "$_val" ]; then
    echo "error: ${_desc} is empty; set ${_name} in the configuration section." >&2
    exit 1
  fi
}

# ──────────────────────────────────────────────
# Configuration — replace these with your values
# ──────────────────────────────────────────────
PROJECT_ID=""                        # Your GCP project ID
PROJECT_NUMBER=""                    # Your GCP project number
SERVICE_ACCOUNT_NAME="baseten-oidc"  # Service account name
POOL_NAME="baseten-pool"             # Workload Identity Pool name
PROVIDER_NAME="baseten-provider"     # Workload Identity Provider name
BASETEN_ORG_ID=""                    # From `truss whoami --show-oidc`
BASETEN_TEAM_ID=""                   # From `truss whoami --show-oidc`

require_non_empty PROJECT_ID "GCP project ID"
require_non_empty PROJECT_NUMBER "GCP project number"
require_non_empty BASETEN_ORG_ID "Baseten organization ID"
require_non_empty BASETEN_TEAM_ID "Baseten team ID"
require_non_empty SERVICE_ACCOUNT_NAME "Service account name"
require_non_empty POOL_NAME "Workload Identity Pool name"
require_non_empty PROVIDER_NAME "Workload Identity Provider name"

OIDC_ISSUER_URL="https://oidc.baseten.co"
OIDC_AUDIENCE="oidc.baseten.co"
SA_EMAIL="${SERVICE_ACCOUNT_NAME}@${PROJECT_ID}.iam.gserviceaccount.com"

# ──────────────────────────────────
# 1. Create the service account
# ──────────────────────────────────
echo "Creating service account ${SERVICE_ACCOUNT_NAME}..."
gcloud iam service-accounts create "${SERVICE_ACCOUNT_NAME}" \
  --project="${PROJECT_ID}" \
  --display-name="Baseten OIDC Service Account"

# ──────────────────────────────────
# 2. Grant Artifact Registry reader
# ──────────────────────────────────
echo "Granting Artifact Registry reader role..."
gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
  --member="serviceAccount:${SA_EMAIL}" \
  --role="roles/artifactregistry.reader"

# ──────────────────────────────────
# 3. Grant Cloud Storage object viewer
# ──────────────────────────────────
echo "Granting Cloud Storage object viewer role..."
gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
  --member="serviceAccount:${SA_EMAIL}" \
  --role="roles/storage.objectViewer"

# ──────────────────────────────────
# 4. Create the Workload Identity Pool
# ──────────────────────────────────
echo "Creating Workload Identity Pool..."
gcloud iam workload-identity-pools create "${POOL_NAME}" \
  --project="${PROJECT_ID}" \
  --location="global" \
  --display-name="Baseten Workload Identity Pool"

# ──────────────────────────────────
# 5. Create the Workload Identity Provider
# ──────────────────────────────────
ATTRIBUTE_CONDITION="google.subject.startsWith('v=1:org=${BASETEN_ORG_ID}:team=${BASETEN_TEAM_ID}:')"

echo "Creating Workload Identity Provider..."
gcloud iam workload-identity-pools providers create-oidc "${PROVIDER_NAME}" \
  --project="${PROJECT_ID}" \
  --location="global" \
  --workload-identity-pool="${POOL_NAME}" \
  --issuer-uri="${OIDC_ISSUER_URL}" \
  --allowed-audiences="${OIDC_AUDIENCE}" \
  --attribute-mapping="google.subject=assertion.sub" \
  --attribute-condition="${ATTRIBUTE_CONDITION}"

# ──────────────────────────────────
# 6. Allow Workload Identity to impersonate the service account
# ──────────────────────────────────
echo "Binding workload identity to service account..."
gcloud iam service-accounts add-iam-policy-binding "${SA_EMAIL}" \
  --project="${PROJECT_ID}" \
  --role="roles/iam.workloadIdentityUser" \
  --member="principalSet://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/${POOL_NAME}/*"

# ──────────────────────────────────
# Done
# ──────────────────────────────────
echo ""
echo "Setup complete. Service account:"
echo "  ${SA_EMAIL}"
echo ""
echo "Workload Identity Provider:"
echo "  projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/${POOL_NAME}/providers/${PROVIDER_NAME}"
echo ""
echo "Use these values in your Truss configuration."

This grants both Artifact Registry and GCS permissions to the service account. If you only need Artifact Registry or GCS access (not both), comment out or remove the role binding you don’t need (step 2 or step 3).

To find your GCP project number, run: gcloud projects describe PROJECT_ID --format="value(projectNumber)"

If you prefer to walk through each step manually, or need to customize individual resources, follow the instructions below.

Create a service account

Create a service account that Baseten workloads will impersonate.

gcloud iam service-accounts create baseten-oidc \
  --display-name="Baseten OIDC Service Account"

Grant permissions to the service account

Grant the service account access to the resources you need. You can grant one or both depending on your use case.

Artifact Registry access (for base images)

Grant read access to Artifact Registry for pulling container images.

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:baseten-oidc@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/artifactregistry.reader"

GCS access (for model weights)

Grant read access to Cloud Storage for downloading model weights.

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:baseten-oidc@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/storage.objectViewer"

Create a Workload Identity Pool

Create a pool to manage external identities from Baseten.

gcloud iam workload-identity-pools create baseten-pool \
  --location="global" \
  --display-name="Baseten Workload Identity Pool"

Create a Workload Identity Provider

Add Baseten as an OIDC provider in the pool.

gcloud iam workload-identity-pools providers create-oidc baseten-provider \
  --location="global" \
  --workload-identity-pool="baseten-pool" \
  --issuer-uri="https://oidc.baseten.co" \
  --allowed-audiences="oidc.baseten.co" \
  --attribute-mapping="google.subject=assertion.sub" \
  --attribute-condition="google.subject.startsWith('v=1:org=Mvg9jrRd:team=AviIZ0y3:')"

The attribute mapping google.subject=assertion.sub maps the OIDC sub claim into the google.subject attribute. After this mapping, you can use google.subject everywhere (including in attribute-condition) to reference the subject claim.

GCP doesn’t support wildcard subject claims. Use startsWith() in attribute-condition to match workloads by prefix. Replace the organization and team IDs with your own values.

Allow the Workload Identity to impersonate the service account

Grant the workload identity pool permission to act as the service account.

gcloud iam service-accounts add-iam-policy-binding \
  baseten-oidc@PROJECT_ID.iam.gserviceaccount.com \
  --role="roles/iam.workloadIdentityUser" \
  --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/baseten-pool/*"

Using OIDC in your Truss configuration

Once you’ve completed the AWS or GCP setup above, you can configure OIDC authentication in your Truss:

Private registries (ECR, GCR)

For authenticating to private Docker registries using OIDC, see:

• AWS ECR OIDC: Configure OIDC for AWS Elastic Container Registry.
• GCP Artifact Registry OIDC: Configure OIDC for Google Container Registry / Artifact Registry.

Model weights (S3, GCS)

For downloading model weights from cloud storage using OIDC, see:

• AWS S3 OIDC: Configure OIDC for S3 model weights.
• GCS OIDC: Configure OIDC for Google Cloud Storage model weights.

Best practices

Use least-privilege access

Use the most specific subject claim pattern that fits your use case. Create separate roles or Workload Identity providers for different environments, workload types, or models rather than one role with broad permissions. Always test your OIDC configuration in a non-production environment first.

Don’t grant access to v=1:org=*:team=*:*. This allows any Baseten workload to access your resources.

Monitor and audit

• Enable CloudTrail (AWS) or Cloud Audit Logs (GCP) to track OIDC token usage.
• Set up alerts for unexpected access patterns.
• Regularly review which roles are being used.

Troubleshooting

Authentication failures

If your model fails to authenticate:

1. Verify the trust relationship: Ensure your IAM role trusts the Baseten OIDC provider (https://oidc.baseten.co).
2. Check the audience: Confirm the audience is set to oidc.baseten.co.
3. Review subject claim conditions: Verify your sub claim pattern matches the workload identity.
4. Inspect your identifiers: Run truss whoami --show-oidc to confirm your org and team IDs.

Permission denied errors

If authentication succeeds but operations fail:

1. Check IAM policies: Ensure the role has the necessary permissions (for example, s3:GetObject, ecr:BatchGetImage).
2. Verify resource ARNs: Confirm bucket names, registry URLs, and other resource identifiers are correct.
3. Review resource policies: Some resources (like S3 buckets) have their own policies that may block access.

Common error messages

Error	Likely Cause	Solution
”Not authorized to perform sts:AssumeRoleWithWebIdentity”	Trust policy doesn’t match the workload	Check subject claim pattern in trust policy
”Access Denied”	Missing permissions in IAM policy	Add required permissions to the role
”Invalid identity token”	Issuer or audience mismatch	Verify OIDC provider configuration
”Token has expired”	Clock skew or token refresh issue	Contact Baseten support

Debugging with CloudWatch/Cloud Logging

Enable detailed logging to see exactly why authentication or authorization is failing:

AWS CloudTrail: Look for AssumeRoleWithWebIdentity events to see token validation attempts.

GCP Cloud Audit Logs: Check iam.googleapis.com logs for workload identity authentication events.

Migration from long-lived credentials

If you’re currently using long-lived AWS or GCP credentials:

1. Set up OIDC as described above.
2. Update your Truss configuration to use OIDC authentication.
3. Deploy and test your model.
4. Once confirmed working, remove the long-lived credentials.
5. Delete any secrets containing long-lived credentials from Baseten.

Both OIDC and long-lived credential authentication methods are supported. You can migrate gradually, starting with non-production environments.

Limitations

• OIDC tokens can’t be customized.
• Baseten manages token lifetime and claims.
• Only AWS and GCP services are supported.
• GCP doesn’t support wildcard subject claims or subject-based scoping in IAM role conditions. Use the Workload Identity Provider attribute-condition instead.
• Cloudflare R2, Azure containers, and Hugging Face aren’t yet supported.