or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cognito-credentials.mdconfiguration-file-credentials.mdcustom-credential-chains.mddefault-provider-chain.mdenvironment-credentials.mdhttp-credentials.mdindex.mdmetadata-service-credentials.mdprocess-credentials.mdsso-credentials.mdtemporary-credentials.mdweb-identity-credentials.md
tile.json

tessl/npm-aws-sdk--credential-providers

A collection of credential providers for AWS SDK, enabling authentication across different AWS environments and services

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@aws-sdk/credential-providers@3.880.x

To install, run

npx @tessl/cli install tessl/npm-aws-sdk--credential-providers@3.880.0

index.mddocs/

AWS SDK Credential Providers

AWS SDK Credential Providers is a comprehensive TypeScript library that provides a collection of credential providers for AWS SDK clients. It enables seamless authentication across different AWS environments and services without requiring service clients like STS or Cognito to be explicitly imported.

Package Information

  • Package Name: @aws-sdk/credential-providers
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @aws-sdk/credential-providers

Environment Support

This package provides different APIs depending on the runtime environment:

  • Node.js: Full API surface with all credential providers
  • Browser: Limited API with only browser-compatible providers
  • React Native: Similar to browser environment

Node.js Environment

// All providers available in Node.js
import { 
  fromEnv, fromIni, fromCognitoIdentity, fromTemporaryCredentials,
  fromContainerMetadata, fromInstanceMetadata, fromTokenFile,
  fromHttp, fromSSO, fromProcess, fromNodeProviderChain,
  createCredentialChain
} from "@aws-sdk/credential-providers";

Browser Environment

// Limited providers available in browsers
import { 
  fromCognitoIdentity, fromCognitoIdentityPool, fromHttp, 
  fromTemporaryCredentials, fromWebToken
} from "@aws-sdk/credential-providers";

Core Imports

import { 
  fromEnv, 
  fromIni, 
  fromCognitoIdentity, 
  fromTemporaryCredentials,
  fromContainerMetadata,
  fromInstanceMetadata,
  fromTokenFile,
  fromHttp,
  createCredentialChain
} from "@aws-sdk/credential-providers";

For CommonJS:

const { 
  fromEnv, 
  fromIni, 
  fromCognitoIdentity, 
  fromTemporaryCredentials,
  fromContainerMetadata,
  fromInstanceMetadata,
  fromTokenFile,
  fromHttp,
  createCredentialChain
} = require("@aws-sdk/credential-providers");

Basic Usage

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { fromEnv, fromIni, createCredentialChain } from "@aws-sdk/credential-providers";

// Simple environment variable credentials
const client1 = new DynamoDBClient({
  region: "us-east-1",
  credentials: fromEnv()
});

// Credential chain with fallbacks
const client2 = new DynamoDBClient({
  region: "us-east-1",
  credentials: createCredentialChain(
    fromEnv(),
    fromIni({ profile: "default" })
  )
});

Architecture

AWS SDK Credential Providers is built around several key components:

  • Credential Provider Functions: Factory functions that return AwsCredentialIdentityProvider instances
  • Credential Chain System: Composable pattern allowing multiple credential sources to be tried in sequence
  • Environment-Specific Providers: Different providers for browser vs Node.js environments
  • Automatic Refresh: Built-in credential refresh logic when expiration is set
  • Type Safety: Full TypeScript integration with comprehensive type definitions

Capabilities

Environment Variable Credentials

Reads AWS credentials from environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, etc.). The simplest and most common credential source for development and CI/CD environments.

function fromEnv(init?: FromEnvInit): AwsCredentialIdentityProvider;

interface FromEnvInit {
  logger?: Logger;
}

Environment Credentials

Shared Configuration Files

Reads credentials from AWS shared configuration files (~/.aws/credentials and ~/.aws/config). Supports profiles, role assumption, and various credential sources configured in INI format.

function fromIni(init?: FromIniInit): RuntimeConfigAwsCredentialIdentityProvider;

interface FromIniInit {
  profile?: string;
  filepath?: string;
  configFilepath?: string;
  mfaCodeProvider?: (mfaSerial: string) => Promise<string>;
  clientConfig?: STSClientConfig;
  clientPlugins?: Pluggable<any, any>[];
}

Configuration File Credentials

Cognito Identity Credentials

Retrieves temporary AWS credentials using Amazon Cognito Identity pools and identities. Supports both authenticated and unauthenticated identities for mobile and web applications.

function fromCognitoIdentity(options: FromCognitoIdentityParameters): CognitoIdentityCredentialProvider;
function fromCognitoIdentityPool(options: FromCognitoIdentityPoolParameters): CognitoIdentityCredentialProvider;

interface FromCognitoIdentityParameters {
  identityId: string;
  customRoleArn?: string;
  logins?: Record<string, string>;
  clientConfig?: CognitoIdentityClientConfig;
}

Cognito Credentials

Temporary Credentials via STS

Creates temporary credentials using AWS STS AssumeRole API. Supports role chaining, MFA requirements, and custom session policies for fine-grained access control.

function fromTemporaryCredentials(options: FromTemporaryCredentialsOptions): RuntimeConfigAwsCredentialIdentityProvider;

interface FromTemporaryCredentialsOptions {
  params: Omit<AssumeRoleCommandInput, "RoleSessionName"> & { RoleSessionName?: string };
  masterCredentials?: AwsCredentialIdentity | AwsCredentialIdentityProvider;
  clientConfig?: STSClientConfig;
  logger?: Logger;
  clientPlugins?: Pluggable<any, any>[];
  mfaCodeProvider?: (mfaSerial: string) => Promise<string>;
}

Temporary Credentials

Web Identity Token Credentials

Handles OAuth 2.0 and OpenID Connect tokens for web identity federation. Supports integration with external identity providers like Google, Facebook, and custom OIDC providers.

function fromWebToken(init: FromWebTokenInit): AwsCredentialIdentityProvider;
function fromTokenFile(init?: FromTokenFileInit): AwsCredentialIdentityProvider;

interface FromWebTokenInit {
  roleArn: string;
  webIdentityToken: string;
  roleSessionName?: string;
  providerId?: string;
  policyArns?: PolicyDescriptorType[];
  policy?: string;
  durationSeconds?: number;
  clientConfig?: STSClientConfig;
}

interface FromTokenFileInit extends Partial<Omit<FromWebTokenInit, "webIdentityToken">> {
  webIdentityTokenFile?: string;
  logger?: Logger;
}

Web Identity Credentials

Instance and Container Metadata

Retrieves credentials from EC2 instance metadata service (IMDS) and ECS container metadata service. Essential for applications running on AWS compute services.

function fromInstanceMetadata(init?: RemoteProviderInit & CredentialProviderOptions): AwsCredentialIdentityProvider;
function fromContainerMetadata(init?: RemoteProviderInit): AwsCredentialIdentityProvider;

interface RemoteProviderInit {
  timeout?: number;
  maxRetries?: number;
  logger?: Logger;
}

Metadata Service Credentials

HTTP Credentials

General-purpose HTTP credential provider that makes GET requests to retrieve credentials. Supports both browser and Node.js environments with security restrictions for acceptable URLs.

function fromHttp(options: FromHttpOptions): AwsCredentialIdentityProvider;

interface FromHttpOptions {
  awsContainerCredentialsFullUri?: string;
  awsContainerCredentialsRelativeUri?: string;
  awsContainerAuthorizationToken?: string;
  awsContainerAuthorizationTokenFile?: string;
  credentialsFullUri?: string;
  authorizationToken?: string;
  maxRetries?: number;
  timeout?: number;
  logger?: Logger;
}

HTTP Credentials

AWS Single Sign-On (SSO)

Integrates with AWS SSO to provide temporary credentials from cached SSO sessions. Requires AWS CLI SSO configuration and active SSO login session.

function fromSSO(init?: FromSSOInit): AwsCredentialIdentityProvider;

interface FromSSOInit {
  profile?: string;
  filepath?: string;
  configFilepath?: string;
  ssoStartUrl?: string;
  ssoAccountId?: string;
  ssoRegion?: string;
  ssoRoleName?: string;
  clientConfig?: SSOClientConfig;
}

SSO Credentials

External Process Credentials

Executes external processes and parses their JSON output to retrieve credentials. Useful for integration with custom credential management systems and corporate authentication tools.

function fromProcess(init?: FromProcessInit): AwsCredentialIdentityProvider;

interface FromProcessInit {
  profile?: string;
  filepath?: string;
  configFilepath?: string;
}

Process Credentials

Default Node.js Provider Chain

Comprehensive credential provider chain that tries multiple credential sources in order. Includes all common credential sources with sensible defaults and automatic role assumption.

function fromNodeProviderChain(init?: DefaultProviderInit): AwsCredentialIdentityProvider;

interface DefaultProviderInit {
  profile?: string;
  filepath?: string;
  configFilepath?: string;
  ignoreCache?: boolean;
  mfaCodeProvider?: (mfaSerial: string) => Promise<string>;
  clientConfig?: STSClientConfig;
}

Default Provider Chain

Custom Credential Chains

Build custom credential provider chains that try multiple credential sources in sequence. Supports automatic expiration and credential refresh functionality.

function createCredentialChain(
  ...credentialProviders: RuntimeConfigAwsCredentialIdentityProvider[]
): RuntimeConfigAwsCredentialIdentityProvider & CustomCredentialChainOptions;

interface CustomCredentialChainOptions {
  expireAfter(milliseconds: number): AwsCredentialIdentityProvider & CustomCredentialChainOptions;
}

Custom Credential Chains

Types

type AwsCredentialIdentityProvider = () => Promise<AwsCredentialIdentity>;
type RuntimeConfigAwsCredentialIdentityProvider = (awsIdentityProperties?: AwsIdentityProperties) => Promise<AwsCredentialIdentity>;
type CognitoIdentityCredentialProvider = AwsCredentialIdentityProvider;

interface AwsCredentialIdentity {
  readonly accessKeyId: string;
  readonly secretAccessKey: string;
  readonly sessionToken?: string;
  readonly expiration?: Date;
}

interface AwsIdentityProperties {
  callerClientConfig?: {
    region?: string;
    profile?: string;
  };
}

interface CredentialProviderOptions {
  logger?: Logger;
}

interface Logger {
  info(message?: any, ...optionalParams: any[]): void;
  warn(message?: any, ...optionalParams: any[]): void;
  error(message?: any, ...optionalParams: any[]): void;
  debug(message?: any, ...optionalParams: any[]): void;
}

interface FromCognitoIdentityPoolParameters {
  identityPoolId: string;
  accountId?: string;
  cache?: any;
  userIdentifier?: string;
  customRoleArn?: string;
  logins?: Record<string, string>;
  clientConfig?: CognitoIdentityClientConfig;
}

interface PolicyDescriptorType {
  arn?: string;
}

interface Tag {
  Key: string;
  Value: string;
}

// External types from AWS SDK dependencies:
// - STSClientConfig: Configuration for STS client
// - SSOClientConfig: Configuration for SSO client  
// - CognitoIdentityClientConfig: Configuration for Cognito Identity client
// - AssumeRoleCommandInput: Input parameters for STS AssumeRole operation
// - AssumeRoleWithWebIdentityCommandInput: Input for STS AssumeRoleWithWebIdentity
// - AssumeRoleWithWebIdentityCommandOutput: Output from STS AssumeRoleWithWebIdentity
// - Pluggable<any, any>: Middleware plugin type for client customization