Assume an IAM Role With AWS SDK v3 (STS AssumeRole)

// assume-role.ts: assume a role once and use its temporary credentials for another client.
// Usage: ROLE_ARN=arn:aws:iam::210987654321:role/ReadOnlyAudit EXTERNAL_ID=... npx tsx assume-role.ts
import { STSClient, AssumeRoleCommand, GetCallerIdentityCommand } from "@aws-sdk/client-sts";
import { S3Client, ListBucketsCommand } from "@aws-sdk/client-s3";

const region = process.env.AWS_REGION ?? "us-east-1";
const roleArn = process.env.ROLE_ARN;
if (!roleArn) throw new Error("Set ROLE_ARN to the role you want to assume");

// The STS client itself uses your normal credentials (profile, SSO, environment, instance role).
const sts = new STSClient({ region });

const { Credentials, AssumedRoleUser } = await sts.send(
  new AssumeRoleCommand({
    RoleArn: roleArn,
    RoleSessionName: `audit-${process.env.USER ?? "script"}`.slice(0, 64), // 2-64 chars: letters, digits, _+=,.@-
    DurationSeconds: 3600, // 900 up to the role's maximum session duration; 3600 max when chaining roles
    ExternalId: process.env.EXTERNAL_ID, // only if the trust policy requires sts:ExternalId
  }),
);
if (!Credentials?.AccessKeyId || !Credentials.SecretAccessKey) throw new Error("AssumeRole returned no credentials");

// Map the STS response shape onto the SDK's credential shape.
const credentials = {
  accessKeyId: Credentials.AccessKeyId,
  secretAccessKey: Credentials.SecretAccessKey,
  sessionToken: Credentials.SessionToken,
  expiration: Credentials.Expiration,
};

const who = await new STSClient({ region, credentials }).send(new GetCallerIdentityCommand({}));
console.log(`Assumed ${AssumedRoleUser?.Arn} until ${Credentials.Expiration?.toISOString()}`);
console.log(`Calls now run as account ${who.Account}`);

const s3 = new S3Client({ region, credentials });
const { Buckets } = await s3.send(new ListBucketsCommand({}));
console.log(`${Buckets?.length ?? 0} buckets visible to the role`);

Assumed arn:aws:sts::210987654321:assumed-role/ReadOnlyAudit/audit-jane until 2026-09-28T14:50:35.649Z
Calls now run as account 210987654321
2 buckets visible to the role

// refreshing-role-credentials.ts: a credential provider that calls AssumeRole explicitly and
// refreshes five minutes before the session expires. Useful when you need the raw AssumeRole
// response (session tags, source identity, token size) and still want long-running clients.
import { STSClient, AssumeRoleCommand, type AssumeRoleCommandInput } from "@aws-sdk/client-sts";
import type { AwsCredentialIdentity, AwsCredentialIdentityProvider } from "@aws-sdk/types";

const REFRESH_BEFORE_MS = 5 * 60_000;

export function assumeRoleProvider(sts: STSClient, input: AssumeRoleCommandInput): AwsCredentialIdentityProvider {
  let cached: AwsCredentialIdentity | undefined;
  let pending: Promise<AwsCredentialIdentity> | undefined;

  const fetchCredentials = async (): Promise<AwsCredentialIdentity> => {
    const { Credentials } = await sts.send(new AssumeRoleCommand(input));
    if (!Credentials?.AccessKeyId || !Credentials.SecretAccessKey || !Credentials.Expiration) {
      throw new Error(`AssumeRole for ${input.RoleArn} returned incomplete credentials`);
    }
    return {
      accessKeyId: Credentials.AccessKeyId,
      secretAccessKey: Credentials.SecretAccessKey,
      sessionToken: Credentials.SessionToken,
      expiration: Credentials.Expiration,
    };
  };

  return async () => {
    const fresh = cached?.expiration && cached.expiration.getTime() - Date.now() > REFRESH_BEFORE_MS;
    if (cached && fresh) return cached;
    // One AssumeRole call at a time, even when many requests ask for credentials at once.
    pending ??= fetchCredentials().finally(() => {
      pending = undefined;
    });
    cached = await pending;
    return cached;
  };
}

// use-refreshing.ts: long-running worker that keeps using an assumed role.
import { STSClient } from "@aws-sdk/client-sts";
import { SQSClient, ReceiveMessageCommand } from "@aws-sdk/client-sqs";
import { assumeRoleProvider } from "./refreshing-role-credentials.js";

const region = process.env.AWS_REGION ?? "us-east-1";
const credentials = assumeRoleProvider(new STSClient({ region }), {
  RoleArn: "arn:aws:iam::210987654321:role/QueueWorker",
  RoleSessionName: "queue-worker",
  DurationSeconds: 3600,
  SourceIdentity: "queue-worker", // needs sts:SetSourceIdentity; can't be changed later in the session
  Tags: [{ Key: "team", Value: "payments" }], // needs sts:TagSession in the trust policy
});

const sqs = new SQSClient({ region, credentials });
const queueUrl = "https://sqs.us-east-1.amazonaws.com/210987654321/orders";
for (let i = 0; i < 3; i++) {
  const { Messages } = await sqs.send(new ReceiveMessageCommand({ QueueUrl: queueUrl, WaitTimeSeconds: 20 }));
  console.log(`poll ${i + 1}: ${Messages?.length ?? 0} messages`);
}

// cross-account-audit.ts: assume the same read-only role in several accounts and collect one fact from each.
// Usage: ACCOUNTS=111111111111,222222222222 ROLE_NAME=ReadOnlyAudit npx tsx cross-account-audit.ts
import { STSClient, AssumeRoleCommand } from "@aws-sdk/client-sts";
import { S3Client, ListBucketsCommand } from "@aws-sdk/client-s3";

const region = process.env.AWS_REGION ?? "us-east-1";
const accounts = (process.env.ACCOUNTS ?? "").split(",").map((a) => a.trim()).filter((a) => /^\d{12}$/.test(a));
const roleName = process.env.ROLE_NAME ?? "ReadOnlyAudit";
const sts = new STSClient({ region });

// A session policy narrows the role for this run: the session gets only what both policies allow.
const sessionPolicy = JSON.stringify({
  Version: "2012-10-17",
  Statement: [{ Effect: "Allow", Action: "s3:ListAllMyBuckets", Resource: "*" }],
});

const results: { Account: string; Buckets: number | string; Error: string }[] = [];
for (const account of accounts) {
  try {
    const { Credentials } = await sts.send(
      new AssumeRoleCommand({
        RoleArn: `arn:aws:iam::${account}:role/${roleName}`,
        RoleSessionName: `bucket-audit-${account}`,
        DurationSeconds: 900, // shortest allowed; enough for one account
        Policy: sessionPolicy,
      }),
    );
    if (!Credentials?.AccessKeyId || !Credentials.SecretAccessKey) throw new Error("no credentials returned");
    const s3 = new S3Client({
      region,
      credentials: {
        accessKeyId: Credentials.AccessKeyId,
        secretAccessKey: Credentials.SecretAccessKey,
        sessionToken: Credentials.SessionToken,
        expiration: Credentials.Expiration,
      },
    });
    const { Buckets } = await s3.send(new ListBucketsCommand({}));
    results.push({ Account: account, Buckets: Buckets?.length ?? 0, Error: "" });
  } catch (err) {
    // One broken account (missing role, wrong trust policy, SCP) shouldn't stop the audit.
    results.push({ Account: account, Buckets: "-", Error: err instanceof Error ? `${err.name}: ${err.message}` : String(err) });
  }
}
console.table(results);

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowAuditRunnerWithExternalId",
      "Effect": "Allow",
      "Principal": { "AWS": "arn:aws:iam::111111111111:role/AuditRunner" },
      "Action": "sts:AssumeRole",
      "Condition": { "StringEquals": { "sts:ExternalId": "4f1c2a9e-audit" } }
    },
    {
      "Sid": "AllowSessionTagsAndSourceIdentity",
      "Effect": "Allow",
      "Principal": { "AWS": "arn:aws:iam::111111111111:role/AuditRunner" },
      "Action": ["sts:TagSession", "sts:SetSourceIdentity"]
    }
  ]
}

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AssumeAuditRoleInMemberAccounts",
      "Effect": "Allow",
      "Action": ["sts:AssumeRole", "sts:TagSession", "sts:SetSourceIdentity"],
      "Resource": "arn:aws:iam::*:role/ReadOnlyAudit"
    }
  ]
}