AWS STS Role Switcher

A command-line utility that helps users switch between different AWS roles using temporary security credentials.

Capabilities

Assumes an AWS IAM role

The utility should assume a specified IAM role using temporary security credentials. It should accept a role ARN and session name as input parameters, and return the temporary credentials (access key, secret key, and session token).

• Given a valid role ARN "arn:aws:iam::123456789012:role/TestRole" and session name "test-session", the function returns temporary credentials with AccessKeyId, SecretAccessKey, and SessionToken @test
• Given a role ARN with an invalid format (e.g., "invalid-arn"), the function throws a validation error @test

Gets caller identity information

The utility should retrieve information about the AWS identity making the request. This includes the account ID, user ID, and ARN of the calling entity.

• When called with valid credentials, the function returns an object containing UserId, Account, and Arn properties @test

Configures client with region

The utility should allow configuration of the AWS region for the STS client. The region should be configurable and the client should use this region for all subsequent operations.

• Given a region "us-west-2", the client is configured with this region and uses it for API calls @test

Implementation

@generates

API

/**
 * Configuration options for the role switcher
 */
export interface RoleSwitcherConfig {
  region: string;
}

/**
 * Temporary credentials returned after role assumption
 */
export interface TemporaryCredentials {
  accessKeyId: string;
  secretAccessKey: string;
  sessionToken: string;
  expiration?: Date;
}

/**
 * Identity information for the current caller
 */
export interface CallerIdentity {
  userId: string;
  account: string;
  arn: string;
}

/**
 * Creates a role switcher with the specified configuration
 */
export function createRoleSwitcher(config: RoleSwitcherConfig): RoleSwitcher;

/**
 * Role switcher class for managing AWS role assumptions
 */
export class RoleSwitcher {
  constructor(config: RoleSwitcherConfig);

  /**
   * Assumes the specified IAM role and returns temporary credentials
   * @param roleArn - The ARN of the role to assume
   * @param sessionName - A name for the assumed role session
   * @returns Temporary credentials for the assumed role
   * @throws Error if the role ARN is invalid or assumption fails
   */
  assumeRole(roleArn: string, sessionName: string): Promise<TemporaryCredentials>;

  /**
   * Gets information about the current caller identity
   * @returns Identity information for the current caller
   */
  getCallerIdentity(): Promise<CallerIdentity>;
}

Dependencies { .dependencies }

AWS SDK STS Client { .dependency }

Provides AWS Security Token Service operations for managing temporary security credentials and role assumption.

@satisfied-by