Cloud Providers (Preview)

Connect Oz cloud agents to your AWS and GCP services.

Oz cloud agents can securely access cloud providers using short-lived OpenID Connect credentials.

This page explains how to configure a cloud agent environment to automatically authenticate to your cloud provider. Oz has built-in support for AWS and GCP, and can work with any provider that supports OIDC tokens.

Prerequisites

A Warp account (create an account at oz.warp.dev)
A cloud provider account

Follow the section for your cloud provider.

AWS

Step 1: Create an OIDC identity provider

The first step is to configure your AWS account to trust OIDC tokens produced by Oz.

Open the AWS IAM console at https://console.aws.amazon.com/iam.
Click Identity Providers, then click Add provider.
Set the provider type to OpenID Connect.
Set the Provider URL to https://app.warp.dev.
Set the Audience to sts.amazonaws.com.
Copy the ARN of the new identity provider, which will look like: arn:aws:iam::<account-id>:oidc-provider/app.warp.dev.

Step 2: Configure an IAM role

Next, you will need to set up an AWS IAM role with a trust policy that links it to the OIDC provider.

Open the AWS IAM console at https://console.aws.amazon.com/iam.
Click Roles, then click Create role.
Select Custom trust policy, and fill in the following JSON trust policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowOzFederation",
      "Effect": "Allow",
      "Principal": {
        "Federated": "<oidc-provider-arn>"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "app.warp.dev:aud": "sts.amazonaws.com"
        },
        "StringLike": {
          "app.warp.dev:sub": "scoped_principal:<team-uid>/*"
        }
      }
    }
  ]
}

You will need to replace:

<oidc-provider-arn> with the ARN of the OIDC provider added in Step 1.
<team-uid> with your Warp team UID. This is the last component of your Admin Panel URL. For example, if the Admin Panel URL is https://app.warp.dev/admin/abc123def456, your team UID would be abc123def456. You can also get your team UID from the oz whoami command.

The example above uses StringLike with the scoped_principal:<team-uid>/* pattern to allow any user or automation on your team to assume the role. See the subject claim for the full format of app.warp.dev:sub.

To restrict the role to a specific user, use StringEquals with the fully qualified subject:

...
"Condition": {
  "StringEquals": {
    "app.warp.dev:aud": "sts.amazonaws.com",
    "app.warp.dev:sub": "scoped_principal:<team-uid>/user:<user-uid>"
  }
}
...

To allow multiple specific principals, use a list of subjects:

...
"Condition": {
  "StringEquals": {
    "app.warp.dev:aud": "sts.amazonaws.com",
    "app.warp.dev:sub": [
      "scoped_principal:<team-uid>/user:<user-uid-1>",
      "scoped_principal:<team-uid>/user:<user-uid-2>",
      "scoped_principal:<team-uid>/service_account:<sa-uid>"
    ]
  }
}
...

Click Next and add permissions policies. These policies determine what Oz agents can access in your AWS account.
Click Next and enter a role name and optional description.
Click Create role, then open the role and note down the role ARN. This will be of the form arn:aws:iam::<account-id>:role/<role-name>.

Step 3: Enable AWS federation in your cloud agent environment

Finally, configure the Oz cloud agent environment to use your new AWS role.

Open the Oz web app at https://oz.warp.dev.
Create or edit an environment. See Environments for instructions.
Expand the AWS section and enter the AWS role ARN from Step 2.
Save the environment.

Oz agents running in this environment will now automatically assume the configured role when using the aws CLI or a compatible SDK.

GCP

Step 1: Create a Workload Identity Pool and Provider

The Oz GCP integration uses Workload Identity Federation. You will need to configure a pool and provider to trust OIDC tokens produced by Oz.

These instructions use the gcloud tool. You may also follow the OIDC instructions in Configure Workload Identity Federation with other identity providers to use the GCP console or Terraform.

Create a Workload Identity Pool using the gcloud CLI:

gcloud iam workload-identity-pools create "<pool-id>" --location=global

Replace <pool-id> with the desired identifier for your pool, such as oz-agent-pool.

Create a Provider within the pool:

gcloud iam workload-identity-pools providers create-oidc \
    "<provider-id>" \
    --location=global \
    "--workload-identity-pool=<pool-id>" \
    --issuer-uri="https://app.warp.dev" \
    "--attribute-mapping=google.subject=assertion.sub,google.groups=assertion.teams,attribute.environment=assertion.environment" \
    "--attribute-condition='<team-uid>' in assertion.teams"

Replace <pool-id> with the ID you used above, and <provider-id> with the desired identifier for your provider, such as oz-oidc-provider.

Replace <team-uid> with the UID of your Warp team. This is the last component of your Admin Panel URL. For example, if the admin panel URL is https://app.warp.dev/admin/abc123def456, your team UID would be abc123def456.

Step 2: Configure IAM policies

You will need to configure IAM policies in GCP that allow Oz agents in the Workload Identity Federation pool access to resources.

To give all Oz agents on your team read-only access to all Compute Engine resources in a project, for example, you would run:

gcloud projects add-iam-policy-binding <project-id> \
    --member "principalSet://iam.googleapis.com/projects/<project-number>/locations/global/workloadIdentityPools/<pool-id>/attribute.teams/<team-id>" \
    --role "roles/compute.viewer"

See Workload Identity Federation principal types for the full syntax supported.

Step 3: Enable Workload Identity Federation in your cloud agent environment

Finally, configure the Oz cloud agent environment to use your Workload Identity Federation provider.

Open the Oz web app at https://oz.warp.dev.
Create or edit an environment. See Environments for instructions.
Expand the GCP section and enter the project number, pool ID, and provider ID from Step 1.
Save the environment.

Oz agents running in this environment will now automatically configure Application Default Credentials to use the configured pool. Both the GOOGLE_APPLICATION_CREDENTIALS and CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE environment variables are set, so both the gcloud CLI and official Google SDKs will use the Oz federated credentials. Oz uses executable-sourced credentials to configure ADC for automatic token rotation.

Other providers

To authenticate from Oz to another provider that supports OIDC federation, you can issue tokens directly.

Within the agent environment, use the oz federate issue-token command to produce an OIDC token with your provider as the audience:

oz federate issue-token --audience your-provider.com --output-format json

Optionally, add --duration <duration> to customize the token validity. This cannot exceed the maximum runtime of an Oz agent.

You may then exchange this token for provider-specific credentials.

OIDC token claims

All Oz OIDC tokens include standard claims like iss (issuer) and iat (issued at).

Audience

The aud claim will reflect the default for your cloud provider. For AWS, this is always sts.amazonaws.com. For GCP, it is derived from the Workload Identity Federation provider, such as https://iam.googleapis.com/projects/<project-number>/locations/global/workloadIdentityPools/<pool-id>/providers/<provider-id>.

Subject (`sub`)

The sub claim is set to the identity that an Oz agent is executing as. This will either be a Warp user ID or an autogenerated account ID for team-scoped agent runs.

By default, the sub claim uses the format <principal-type>:<principal-id>:

user:abc123def456: Identifies a user with ID abc123def456
service_account:abc123def456: Identifies your autogenerated team account

When authenticating to AWS, Oz will use a different sub claim format, because AWS trust policies cannot match on custom OIDC claims. The format above will be prefixed with your team UID:

scoped_principal:xyz789/user:abc123def456: Identifies the user abc123def456, who is a member of team xyz789.
scoped_principal:user:abc123def456: Identifies the user abc123def456, who is not on any team.
scoped_principal:xyz789/service_account:abc123def456: Identifies the autogenerated account for team xyz789.

In addition, user OIDC tokens include an email claim with the user’s email address.

To get possible user ID values, use the oz whoami command:

oz whoami
User ID: abc123
Email: user@warp.dev
Team ID: xyz789
Team Name: My Team

You can also check the user IDs from past runs using the Oz API:

curl https://app.warp.dev/api/v1/agent/runs -H "Authorization: Bearer $WARP_API_KEY"
{
    "runs": [
        {
            ...
            "creator": {
                "type": "user",
                "uid": "<user-id>",
                "display_name": "User Name",
                "email": "user@warp.dev"
            }
        }
    ]
}

Team

Every token includes a teams claim. The value will be a list with your team UID - currently, this list only ever contains a single value.

Oz run

The following claims are derived from an Oz agent run:

run_id: the unique identifier for the individual run. This is not suitable for configuring access, but is useful to log for debugging.
environment: the unique identifier for the agent’s Environment.
agent_name: the name of the Skill that the agent was invoked with.
skill_spec: the canonical identifier for the skill, such as github-org/github-repo:.warp/skills/skill-name/SKILL.md.
host: the execution host. This will either be warp, for Warp-hosted agents, or the worker ID if self-hosting.

Example token

The following OIDC token references an Oz agent running as a specific Warp user:

// JWT Header
{
    "typ": "JWT",
    "alg": "ES256",
    "kid": "<example-key-id>"
}
// JWT Payload
{
    "aud": ["sts.amazonaws.com"],
    "sub": "user:<example-user-id>",
    "email": "user@warp.dev",
    "teams": ["<example-team-id>"],
    "run_id": "<example-id>",
    "environment": "<example-id>",
    "agent_name": "<example-name>",
    "skill_spec": "<example-spec>",
    "host": "warp",
    "iss": "https://app.warp.dev",
    "jti": "<example-id>",
    "exp": 1775210175,
    "iat": 1775206575,
    "nbf": 1775206575
}