API & Reference > CLI

Federated identity tokens

Issue short-lived OIDC identity tokens from a running agent so it can authenticate to cloud providers without long-lived credentials.

oz federate issues short-lived OIDC identity tokens for the agent that’s currently running. Use these tokens to authenticate to cloud providers (AWS, GCP, Azure, and other OIDC-aware systems) without baking long-lived credentials into your environment.

This command can only be called from inside a running agent session — typically as part of a skill, a tool, or a script the agent executes while a run is in progress.

When to use federation

Use federated identity tokens when you want an agent to act against a cloud account without storing service-account keys, access keys, or refresh tokens in the environment.

Short-lived credentials - Tokens expire on a schedule you choose. Even if a token leaks, its blast radius is bounded.
No secret rotation - Federation removes the need to rotate static keys in environments or secrets.
Per-run identity - Each run can claim a different subject (user, team, environment, skill, run ID), giving you fine-grained IAM policies.

For background on federation, see your cloud provider’s workload identity federation guide (for example, Google Cloud’s workload identity federation or AWS IAM Identity Center).

`oz federate issue-token`

Issue an OIDC identity token for the current run.

oz federate issue-token \
  --run-id <RUN_ID> \
  --audience <AUDIENCE> \
  [--duration <DURATION>] \
  [--subject-template <COMPONENT> ...]

Flags

--run-id <RUN_ID> - The ID of the cloud agent run requesting the token. Cloud agent runs set OZ_RUN_ID to the current run ID, but you must still pass this flag.
--audience <AUDIENCE> - The aud claim for the issued token. Set this to the value your cloud provider’s identity pool expects (for example, an AWS IAM Identity Center audience or a GCP workload identity pool URL).
--duration <DURATION> - Requested token lifetime from 5 minutes to 3 hours. Accepts human-readable durations such as 30m or 2h30m and defaults to 1h.
--subject-template <COMPONENT> ... - Controls how the OIDC token’s sub claim is formatted. Pass one or more components, which are joined to form the subject. Defaults to principal (for example, user:my-user-id).

Subject template components

By default, oz federate issue-token builds sub from principal. The result is user:USER_UID for a user or service_account:SERVICE_ACCOUNT_UID for an agent.

Pass each component as a separate argument. Do not quote the whole list. The command joins components in the order you supply them and separates them with commas. It fails if a component isn’t available for the current principal or run. Colons and commas within component values become underscores.

Use principal, scoped_principal, or any available claim listed under principal claims and run claims, except user and service_account. Use principal in place of those emitted claim names. See the subject claim for the principal and scoped_principal formats.

Examples

Issue a one-hour token with the default principal subject:

oz federate issue-token \
  --run-id "$OZ_RUN_ID" \
  --audience AUDIENCE \
  --output-format json

Replace AUDIENCE with the identifier expected by your provider.

Issue a 30-minute token whose subject includes the principal, run, and environment:

oz federate issue-token \
  --run-id "$OZ_RUN_ID" \
  --audience AUDIENCE \
  --duration 30m \
  --subject-template principal run_id environment

For a user, this template produces a subject such as user:abc123,run_id:run-456,environment:env-789.

Using tokens with cloud providers

Once you have a token, exchange it for cloud credentials using your provider’s standard OIDC federation flow. The exchange happens between the cloud provider and your script — the Automation Platform only issues the OIDC token.

For provider setup instructions and the complete token claim reference, see Cloud providers.

A typical AWS flow:

Run oz federate issue-token to get the OIDC JWT.
Call sts:AssumeRoleWithWebIdentity with the JWT and an IAM role ARN.
Use the temporary AWS credentials returned by STS.

A typical GCP flow:

Run oz federate issue-token to get the OIDC JWT.
Call the Security Token Service token endpoint to exchange the JWT for a federated access token.
Optionally impersonate a service account for the final credentials.

Cloud environments - configure the environment your agent runs in.
Secrets - alternative for credentials that can’t be federated.