Credential Providers: fromEnv, fromIni, fromNodeProviderChain

Every AWS call needs credentials, and the AWS SDK for JavaScript v3 makes credential resolution explicit and composable. Instead of a hidden chain baked into the client, v3 exposes each strategy as a small function you can import from @aws-sdk/credential-providers and pass to the credentials option.

This page covers the three you reach for most: fromEnv, fromIni, and fromNodeProviderChain. Understanding them means you never have to guess where a call got its credentials from.

Recipe

Import a provider and pass it as credentials. Omit it to accept the node default chain.

// Terminal: npm install @aws-sdk/credential-providers
import { S3Client } from "@aws-sdk/client-s3";
import { fromIni } from "@aws-sdk/credential-providers";
 
const s3 = new S3Client({
  region: "us-east-1",
  credentials: fromIni({ profile: "staging" }),   // explicit, narrowed source
});

When to reach for this:

• You want a specific, named source rather than whatever the default chain finds.
• You are running locally with multiple AWS profiles and need to pick one.
• You are debugging a "credentials not found" error and want to pin the source.
• You need to assume a role or force environment-only credentials in CI.

Working Example

Choosing a provider by environment keeps local, CI, and production behavior explicit and predictable.

import { S3Client } from "@aws-sdk/client-s3";
import {
  fromEnv,
  fromIni,
  fromNodeProviderChain,
} from "@aws-sdk/credential-providers";
 
function credentialsForEnv() {
  if (process.env.CI) return fromEnv();                    // CI injects keys as env vars
  if (process.env.NODE_ENV === "development") {
    return fromIni({ profile: "dev" });                    // local dev uses a named profile
  }
  return fromNodeProviderChain();                          // prod: SSO, container, or instance role
}
 
const s3 = new S3Client({
  region: "us-east-1",
  credentials: credentialsForEnv(),
});

What this demonstrates:

• Each provider is a function that returns a credential resolver the client calls when it needs to sign.
• fromEnv is deterministic in CI, where secrets arrive as environment variables.
• fromIni targets one named profile for local work, so you never send calls with the wrong account.
• fromNodeProviderChain covers production, where credentials come from an IAM role via container or instance metadata.

Deep Dive

fromEnv

• Reads AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and optionally AWS_SESSION_TOKEN from the environment.
• It only looks at environment variables, so it fails fast if they are absent - useful when you want to guarantee that source.
• Ideal in CI systems and containers that inject credentials as env vars.
• It does not read profiles or instance metadata; it is the narrowest of the three.

fromIni

• Reads the shared config (~/.aws/config) and credentials (~/.aws/credentials) files.
• Select a profile with fromIni({ profile: "name" }); it defaults to default or AWS_PROFILE.
• Supports assumed-role profiles (role_arn + source_profile) and SSO-backed profiles defined in config.
• This is the right choice for local development across multiple accounts.

fromNodeProviderChain

• The composite default. It tries sources in order: environment variables, SSO, shared config/credentials, then container credentials (ECS/Fargate), then EC2 instance metadata (IMDS).
• The first source that yields credentials wins, and the result is cached and refreshed as needed.
• This is what a v3 client uses when you pass no credentials at all, so calling it explicitly mainly documents intent.
• On EC2, ECS, and Lambda it resolves the attached IAM role automatically, which is the recommended production posture.

Passing a Provider vs Omitting It

• Omitting credentials gives you the node default chain (equivalent to fromNodeProviderChain()), which is correct for most server and Lambda code.
• Pass a provider when you need to narrow the source (fromEnv, fromIni) or compose custom behavior.
• Providers are lazy: the function is called when the client first needs to sign, not at construction time.
• You can build one provider and share it across several clients so they all resolve credentials the same way.

Contrast with boto3

boto3 also has a credential chain, but it is implicit: you configure it through ~/.aws/config, environment variables, Session(profile_name=...), or botocore config, and the chain runs inside the client. v3 surfaces the same strategies as named, importable functions you pass in. The resolution order of fromNodeProviderChain mirrors boto3's default chain closely; the difference is that v3 makes the choice a value in your code rather than ambient configuration.

Gotchas

• Expecting fromEnv to read a profile - it only reads environment variables and will fail if they are unset. Fix: use fromIni for profile-based credentials.
• Assuming a provider runs at construction - providers are lazy and resolve on first signing. Fix: do not rely on client construction to validate credentials; make a cheap call to verify.
• IMDS timeouts off of EC2 - fromNodeProviderChain may probe instance metadata and pause when run somewhere without IMDS. Fix: provide env or profile credentials locally so the chain resolves before reaching IMDS.
• Wrong profile silently used - omitting profile falls back to default or AWS_PROFILE, which may not be what you want. Fix: pass fromIni({ profile }) explicitly in multi-account setups.
• Hardcoding keys instead of a provider - inline credentials: { accessKeyId, secretAccessKey } leaks secrets into source. Fix: use a provider or an IAM role, never literals.
• Forgetting the session token - temporary credentials need AWS_SESSION_TOKEN too. Fix: let the provider resolve full temporary credentials rather than passing only key and secret.

Alternatives

FAQs

Related

• SDK v3 Fundamentals Basics - where the credentials option first appears.
• Installing Only the Clients You Need - @aws-sdk/credential-providers is a separate install.
• SDK v3 in the Browser vs Node.js - why the browser needs different credential strategies (Cognito, no IMDS).
• SDK v3 Fundamentals Best Practices - credential hygiene rules.

Stack versions: This page was written for the AWS SDK for JavaScript v3 on Node.js 18+ (and boto3 1.43.x / Python 3.10+ where contrasted).