Cloud providers

Cloud agents can securely access AWS, GCP, and other cloud providers using short-lived OpenID Connect (OIDC) credentials. Configure your cloud agent environment to automatically authenticate to your cloud provider without storing long-lived keys, using Warp's built-in OIDC federation support.

Prerequisites

• A Warp account. You can <a href=https://oz.warp.dev>create an account in the Oz web app.
• 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 the Automation Platform.

1. Open the AWS IAM console.
2. Click Identity Providers, then click Add provider.
3. Set the provider type to OpenID Connect.
4. Set the Provider URL to https://app.warp.dev.
5. Set the Audience to sts.amazonaws.com.
6. 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.

1. Open the AWS IAM console.
2. Click Roles, then click Create role.
3. 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>"
		]
	}
}
...

4. Click Next and add permissions policies. These policies determine what agents can access in your AWS account.
5. Click Next and enter a role name and optional description.
6. 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 cloud agent environment to use your new AWS role.

1. Open the <a href=https://oz.warp.dev>Oz web app.
2. Create or edit an environment. See Environments for instructions.
3. Expand the AWS section and enter the AWS role ARN from Step 2.
4. Save the environment.

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 Automation Platform GCP integration uses Workload Identity Federation. You will need to configure a pool and provider to trust OIDC tokens produced by the Automation Platform.

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

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

2. 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 agents in the Workload Identity Federation pool access to resources.

To give all 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>/group/<team-uid>" \
    --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 cloud agent environment to use your Workload Identity Federation provider.

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

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 Automation Platform federated credentials. The Automation Platform uses executable-sourced credentials to configure ADC for automatic token rotation.

Automatic gcloud sign-in

Environment variables alone are enough for the Google SDKs, but gcloud reports no active account until it signs in through its own auth system, and some tooling depends on an active account. During provider setup, the Automation Platform therefore also runs gcloud auth login against the federated credential file so gcloud reports the federated identity as its active account.

This step is best-effort and never blocks the run:

• gcloud isn't installed - The Automation Platform skips the sign-in. The ADC environment variables still provide credentials to the Google SDKs.
• Sign-in fails or times out - The Automation Platform logs the failure and continues. The ADC environment variables still work, so a run only loses the active-account convenience.

To confirm the account inside a run, use gcloud auth list.

Other providers

To authenticate from the Automation Platform 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 --run-id "$OZ_RUN_ID" --audience AUDIENCE --output-format json

Cloud agent runs set OZ_RUN_ID to the current run's ID. Replace AUDIENCE with the identifier expected by your provider.

See the oz federate issue-token reference for token lifetime and subject customization options.

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

OIDC token claims

All Automation Platform OIDC tokens include the following standard claims:

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 identifies the principal that an agent is executing as: a Warp user or a dedicated agent.

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

Use --subject-template to include other available claims in sub.

When authenticating to AWS, the Automation Platform uses a different sub claim format because AWS trust policies can't match on custom OIDC claims. The format above is 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.

The scoped_principal component isn't available for users who belong to multiple teams.

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

oz whoami
User ID: abc123
Email: [email protected]
Team ID: xyz789
Team Name: My Team

You can also check the user IDs from past runs using the Warp Platform 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": "[email protected]"
            }
        }
    ]
}

Principal claims

Tokens include claims that describe the user or agent:

• user: the user's UID. Included only for user tokens.
• service_account: the service account UID. Included only for agent tokens.
• email: the user's email address. Included only for user tokens with an email address.
• teams: the UIDs of the teams the principal belongs to. Users on multiple teams get multiple values, and users on no team don't get this claim.
• factory_uid: the factory UID. Included only for service agents belonging to a factory.
• agent_type: the configured factory agent type. Included only for agent tokens with a configured agent type.

Run claims

The following claims are derived from an 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 configured agent name.
• 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 is warp for Warp-hosted agents or the configured worker host for self-hosted agents.

Example token

The following OIDC token references an 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>",
    "user": "<example-user-id>",
    "email": "[email protected]",
    "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
}