AWS - Tembo Docs

Tembo acts as an OIDC identity provider. Your agents receive short-lived STS credentials that expire automatically — no AWS access keys are ever 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 have access to the AWS Agent Toolkit — AWS’s official MCP service covering 15,000+ APIs across every AWS service:

call_aws — execute any authenticated AWS API call
suggest_aws_commands — translate natural language to AWS API calls
run_script — run Python code with AWS API access in a sandboxed environment
search_documentation / read_documentation — search and read all AWS documentation
get_presigned_url — generate pre-signed S3 URLs

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. Each gets its own label and an isolated MCP server session, so a production and a staging account never share credentials.

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 AWS credentials. For each agent run:

Tembo mints a short-lived RS256 JWT (5-minute TTL) signed with its OIDC private key, carrying iss of the Tembo issuer, aud of sts.amazonaws.com, and sub of org:<your-workspace-id>
Tembo calls sts:AssumeRoleWithWebIdentity against your role, presenting that JWT. This call carries no AWS credentials of its own — the token is the identity
STS finds the OIDC provider in your account matching the token’s issuer, fetches Tembo’s public JWKS to verify the signature, then evaluates your trust policy conditions
The resulting temporary credentials (1-hour TTL) are injected into the agent’s sandbox and never leave it

Because the 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.

Credentials expire during a long agent run

Sessions are 1 hour. If your role’s maximum session duration is lower than 3600 seconds, sessions will be shorter than expected — raise it to 3600.

Agent can't reach AWS APIs

The agent sandbox requires outbound access to https://aws-mcp.us-east-1.api.aws for the AWS Agent Toolkit MCP service. On self-hosted deployments in a private network, confirm egress to that endpoint is allowed.

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