AWS - Tembo Docs

Tembo acts as an OIDC identity provider. Agents request short-lived STS credentials on demand from any session or automation in your workspace — no long-lived AWS access keys are stored in Tembo. Connecting an account takes two things: an OIDC provider and an IAM role in your AWS account. You can let Tembo’s CloudFormation template create both, or create them yourself with your own tooling.

What agents can do

Once connected, agents can run AWS CLI commands and programs that use an AWS SDK. Each enabled integration can be configured as a standard AWS profile inside the agent sandbox. Agents can list the accounts available to your workspace:

tembo aws profiles

They select an account when running each command:

tembo aws exec staging -- aws sts get-caller-identity
tembo aws exec production -- aws s3 ls

The selector can be the integration’s environment label, generated profile name, AWS account ID, or integration ID. If two integrations use the same label or AWS account ID, use the generated profile name shown by tembo aws profiles. The exec command authenticates on demand and limits the selected profile to its child process. This makes it safe to use different AWS accounts concurrently in one session without changing ambient credentials. Agents can only do what the IAM role permits. The default is ReadOnlyAccess; you control this entirely.

Before you start

You need permission to create IAM roles and identity providers in the target AWS account.

Connect as many AWS accounts as you like. Every enabled AWS integration is available to every session and automation in your workspace; it does not have to be assigned when a session starts. The agent explicitly selects an account for each command.

Choose a setup method

Use the CloudFormation template

Fastest path. Tembo gives you a template that creates the OIDC provider and role for you.

Create the resources yourself

Use your own Terraform, CDK, Pulumi, or the AWS CLI. Full requirements below.

Both produce identical results. Tembo only needs the finished role ARN.

Option 1: Use the CloudFormation template

Open the connect modal

Go to Integrations and click Connect next to AWS. Enter a name for this account, for example production.

Deploy the stack

Click Create via CloudFormation to open a pre-filled stack in your AWS console, then deploy it.If that link returns “Access Denied”, download the template from the connect modal and upload it manually instead: in the CloudFormation console, choose Create stack → With new resources → Upload a template file, then supply your workspace ID when prompted.

Copy the role ARN

When the stack completes, open its Outputs tab and copy the RoleArn value.

Finish in Tembo

Back in the connect modal, switch to Enter ARN manually, paste the ARN, and click Connect.

Option 2: Create the resources yourself

Create two resources in the AWS account you want to connect, then hand Tembo the role ARN.

Find your workspace ID

The role’s trust policy has to name the workspace allowed to assume it. In Tembo, go to Settings → Workspace and copy the value under Workspace ID. The value starts with org_, because a workspace is an organization internally. That’s why the trust policy’s subject is org: followed by this value.

Requirements

Setting	Value
OIDC provider URL	`https://internal.tembo.io`
Audience (client ID)	`sts.amazonaws.com`
Trust policy action	`sts:AssumeRoleWithWebIdentity`
`internal.tembo.io:aud` condition	`sts.amazonaws.com`
`internal.tembo.io:sub` condition	`org:<your-workspace-id>`
Max session duration	3600 seconds
Permissions	Your choice. `ReadOnlyAccess` is the default Tembo suggests.

Three details are easy to get wrong:

The provider must live in the same AWS account as the role. AWS resolves the federated principal locally when the role is assumed, so a provider in another account will not work.
The condition keys drop the scheme. They are internal.tembo.io:sub, not https://internal.tembo.io:sub.
The subject is prefixed. If your workspace ID is org_2vyf1Ja..., the sub value is org:org_2vyf1Ja... — the literal string org: followed by the full ID.

Always pin the sub condition to your workspace ID. The OIDC provider only proves that Tembo signed the token, not which workspace it was issued for. Without the sub condition, a token issued to any other Tembo workspace would satisfy your trust policy.

The OIDC provider

Register https://internal.tembo.io as an IAM OIDC identity provider with sts.amazonaws.com as the only audience. You only need one per AWS account. IAM identity providers are global, so if you manage infrastructure per-region, create it once rather than once per region. If the provider already exists in the account, reuse it instead of creating a second one. Thumbprints do not need maintaining. AWS verifies the JWKS endpoint’s TLS certificate against its own library of trusted root certificate authorities, and only falls back to the configured thumbprint if the certificate is not signed by one of those. Tembo’s endpoint uses a publicly trusted certificate, so a placeholder value of forty zeroes is fine.

The IAM role

Attach this trust policy, replacing the account ID and workspace ID:

Trust policy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::111122223333:oidc-provider/internal.tembo.io"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "internal.tembo.io:aud": "sts.amazonaws.com",
          "internal.tembo.io:sub": "org:org_2vyf1Ja..."
        }
      }
    }
  ]
}

Then attach permissions. Start with arn:aws:iam::aws:policy/ReadOnlyAccess and narrow or widen it to suit. Set the role’s maximum session duration to 3600 seconds to match the session length Tembo requests. The role name does not matter — Tembo identifies the role by ARN.

Terraform

resource "aws_iam_openid_connect_provider" "tembo" {
  url             = "https://internal.tembo.io"
  client_id_list  = ["sts.amazonaws.com"]
  thumbprint_list = ["0000000000000000000000000000000000000000"]
}

data "aws_iam_policy_document" "tembo_assume_role" {
  statement {
    effect  = "Allow"
    actions = ["sts:AssumeRoleWithWebIdentity"]

    principals {
      type        = "Federated"
      identifiers = [aws_iam_openid_connect_provider.tembo.arn]
    }

    condition {
      test     = "StringEquals"
      variable = "internal.tembo.io:aud"
      values   = ["sts.amazonaws.com"]
    }

    condition {
      test     = "StringEquals"
      variable = "internal.tembo.io:sub"
      values   = ["org:${var.tembo_workspace_id}"]
    }
  }
}

resource "aws_iam_role" "tembo" {
  name                 = "tembo-integration"
  assume_role_policy   = data.aws_iam_policy_document.tembo_assume_role.json
  max_session_duration = 3600
}

resource "aws_iam_role_policy_attachment" "tembo_read_only" {
  role       = aws_iam_role.tembo.name
  policy_arn = "arn:aws:iam::aws:policy/ReadOnlyAccess"
}

output "tembo_role_arn" {
  value = aws_iam_role.tembo.arn
}

AWS CLI

ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
TEMBO_WORKSPACE_ID=org_2vyf1Ja...   # from Settings → Workspace

aws iam create-open-id-connect-provider \
  --url https://internal.tembo.io \
  --client-id-list sts.amazonaws.com \
  --thumbprint-list 0000000000000000000000000000000000000000

cat > trust-policy.json <<EOF
{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "Federated": "arn:aws:iam::${ACCOUNT_ID}:oidc-provider/internal.tembo.io" },
    "Action": "sts:AssumeRoleWithWebIdentity",
    "Condition": {
      "StringEquals": {
        "internal.tembo.io:aud": "sts.amazonaws.com",
        "internal.tembo.io:sub": "org:${TEMBO_WORKSPACE_ID}"
      }
    }
  }]
}
EOF

aws iam create-role \
  --role-name tembo-integration \
  --assume-role-policy-document file://trust-policy.json \
  --max-session-duration 3600

aws iam attach-role-policy \
  --role-name tembo-integration \
  --policy-arn arn:aws:iam::aws:policy/ReadOnlyAccess

aws iam get-role --role-name tembo-integration --query 'Role.Arn' --output text

Connect it

Paste the role ARN into the Tembo connect modal under Enter ARN manually and click Connect.

Self-hosted Tembo: replace internal.tembo.io throughout with your instance’s TEMBO_OIDC_ISSUER hostname, scheme stripped. Your instance must serve /.well-known/openid-configuration and /.well-known/jwks.json over public HTTPS, because AWS STS fetches the JWKS itself when a role is assumed — reachability from inside your own network is not enough.

How authentication works

Tembo never stores long-lived AWS credentials. Authentication begins only when an agent uses an AWS integration:

The agent lists the enabled AWS integrations in your workspace and explicitly selects one for a command.
Tembo configures standard AWS profiles that use a credential helper. No static access keys are written to the AWS config.
When the selected profile needs credentials, Tembo mints a short-lived RS256 JWT (5-minute TTL) signed with its OIDC private key. It carries an iss of the Tembo issuer, an aud of sts.amazonaws.com, and a sub of org:<your-workspace-id>.
Tembo calls sts:AssumeRoleWithWebIdentity against the selected role. This call carries no AWS credentials of its own — the token is the identity.
STS finds the OIDC provider in your account, verifies the JWT with Tembo’s public JWKS, evaluates your trust policy, and returns temporary credentials with a 1-hour TTL.
The credential helper caches those temporary credentials in the sandbox and refreshes them when needed while the sandbox or authorized runtime remains active and the integration remains enabled.

The selected profile is scoped to the child process and does not become the sandbox’s default AWS identity. Because the OIDC token is the identity, nothing about this depends on which AWS account Tembo runs in.

Troubleshooting

"Access Denied" when opening the CloudFormation link

The one-click URL fetches the template from an S3 bucket. If the bucket policy has not been updated, the AWS console returns an access denied error. Download the template from the connect modal and upload it manually instead — it creates identical resources.

AssumeRoleWithWebIdentity fails after deploy

Work through these in order:

Provider URL exact match. It must be https://internal.tembo.io — correct scheme, no trailing slash, no typos. STS matches the token’s iss claim against the registered provider URL exactly.
Provider is in the same account as the role. A provider in a different account is not usable.
sub includes the org: prefix. The value is org:org_2vyf1Ja..., not org_2vyf1Ja....
Condition keys have no scheme. internal.tembo.io:sub, not https://internal.tembo.io:sub.
Workspace ID matches. Compare against the value under Workspace ID in Settings → Workspace.

No AWS integrations are available

The workspace does not have an enabled AWS integration. Connect one from Settings → Integrations, then retry the command. Sessions and automations that do not use AWS continue to work normally.

An AWS profile selector is ambiguous or not found

List the enabled profiles again and use the generated profile name or integration ID. Environment labels and AWS account IDs are convenient selectors, but they may match more than one integration.

Credentials stop refreshing during a long-running command

Credentials refresh while the sandbox or authorized runtime remains active and the integration remains enabled. Refresh fails closed if the runtime is no longer authorized or the AWS integration is disabled, removed, or no longer belongs to the workspace.

Agent can't reach AWS APIs

During authentication, the sandbox credential helper contacts the Tembo API, and the Tembo API calls AWS STS. On self-hosted deployments in a private network, confirm that:

The Tembo API or control plane has outbound HTTPS access to AWS STS.
The agent sandbox has outbound HTTPS access to the AWS service endpoints used by the child command.
The agent sandbox only needs access to AWS STS when the child command itself calls STS.

Agent hits permission errors on AWS calls

The role’s policies decide what agents can do, and ReadOnlyAccess is read-only by design. To allow writes, attach additional policies to the role. Note that ReadOnlyAccess does grant s3:Get*, so agents can read object contents — attach an explicit Deny if you need to keep specific buckets out of reach.

Performance Insights or other encrypted data returns access denied

Some AWS features encrypt data with a customer-managed KMS key and require the caller to hold kms:Decrypt on that key. ReadOnlyAccess does not grant kms:Decrypt. Add a scoped statement to the role for the specific key, ideally conditioned on kms:ViaService so it is only usable through the owning service.

​What agents can do

​Before you start

​Choose a setup method

Use the CloudFormation template

Create the resources yourself

​Option 1: Use the CloudFormation template

​Option 2: Create the resources yourself

​Find your workspace ID

​Requirements

​The OIDC provider

​The IAM role

​Terraform

​AWS CLI

​Connect it

​How authentication works

​Troubleshooting

What agents can do

Before you start

Choose a setup method

Option 1: Use the CloudFormation template

Option 2: Create the resources yourself

Find your workspace ID

Requirements

The OIDC provider

The IAM role

Terraform

AWS CLI

Connect it

How authentication works

Troubleshooting