Credential providers

v2: CredentialProviderChain in Node.js resolves credential from sources as following order:

If one of the credential providers above fails to resolve the AWS credential, the chain falls back to next provider until a valid credential is resolved, and the chain will throw an error when all of the providers fail.

In Browser and React Native runtimes, the credential chain is empty, and credentials must be set explicitly.

v3: defaultProvider. The credential sources and fallback order does not change in v3. It also supports AWS IAM Identity Center credentials.

v2: ChainableTemporaryCredentials represents temporary credentials retrieved from AWS.STS. Without any extra parameters, credentials will be fetched from the AWS.STS.getSessionToken() operation. If an IAM role is provided, the AWS.STS.assumeRole() operation will be used to fetch credentials for the role instead. AWS.ChainableTemporaryCredentials differs from AWS.TemporaryCredentials in the way masterCredentials and refreshes are handled. AWS.ChainableTemporaryCredentials refreshes expired credentials using the masterCredentials passed by the user to support chaining of STS credentials. However, AWS.TemporaryCredentials recursively collapses the masterCredentials during instantiation, precluding the ability to refresh credentials which require intermediate, temporary credentials.

The original TemporaryCredentials has been deprecated in favor of ChainableTemporaryCredentials in v2.

v3: fromTemporaryCredentials. You can call fromTemporaryCredentials() from the @aws-sdk/credential-providers package. Here's an example:

import { FooClient } from "@aws-sdk/client-foo";
import { fromTemporaryCredentials } from "@aws-sdk/credential-providers"; // ES6 import
// const { FooClient } = require("@aws-sdk/client-foo");
// const { fromTemporaryCredentials } = require("@aws-sdk/credential-providers"); // CommonJS import

const sourceCredentials = {
  // A credential can be a credential object or an async function that returns a credential object
};
const client = new FooClient({
  credentials: fromTemporaryCredentials({
    masterCredentials: sourceCredentials,
    params: { RoleArn },
  }),
});

v2: CognitoIdentityCredentials Represents credentials retrieved from STS Web Identity Federation using the Amazon Cognito Identity service.

v3: Cognito Identity Credential Provider The @aws/credential-providers package provides two credential provider functions, one of which fromCognitoIdentity takes an identity ID and calls cognitoIdentity:GetCredentialsForIdentity, while the other fromCognitoIdentityPool takes an identity pool ID, calls cognitoIdentity:GetId on the first invocation, and then callsfromCognitoIdentity. Subsequent invocations of the latter do not re-invoke GetId.

The provider implements the "Simplified Flow" described in the Amazon Cognito Developer Guide. The "Classic Flow" which involves calling cognito:GetOpenIdToken and then calling sts:AssumeRoleWithWebIdentity is not supported. Please open a feature request to us if you need it.

// fromCognitoIdentityPool example
import { fromCognitoIdentityPool } from "@aws-sdk/credential-providers"; // ES6 import
// const { fromCognitoIdentityPool } = require("@aws-sdk/credential-providers"); // CommonJS import

const client = new FooClient({
  region: "us-east-1",
  credentials: fromCognitoIdentityPool({
    clientConfig: cognitoIdentityClientConfig, // Optional
    identityPoolId: "us-east-1:1699ebc0-7900-4099-b910-2df94f52a030",
    customRoleArn: "arn:aws:iam::1234567890:role/MYAPP-CognitoIdentity", // Optional
    logins: {
      // Optional
      "graph.facebook.com": "FBTOKEN",
      "www.amazon.com": "AMAZONTOKEN",
      "api.twitter.com": "TWITTERTOKEN",
    },
  }),
});

// fromCognitoIdentity example
import { fromCognitoIdentity } from "@aws-sdk/credential-providers"; // ES6 import
// const { fromCognitoIdentity } = require("@aws-sdk/credential-provider-cognito-identity"); // CommonJS import

const client = new FooClient({
  region: "us-east-1",
  credentials: fromCognitoIdentity({
    clientConfig: cognitoIdentityClientConfig, // Optional
    identityId: "us-east-1:128d0a74-c82f-4553-916d-90053e4a8b0f",
    customRoleArn: "arn:aws:iam::1234567890:role/MYAPP-CognitoIdentity", // Optional
    logins: {
      // Optional
      "graph.facebook.com": "FBTOKEN",
      "www.amazon.com": "AMAZONTOKEN",
      "api.twitter.com": "TWITTERTOKEN",
    },
  }),
});

v2: EC2MetadataCredentials

v3: fromInstanceMetadata. Creates a credential provider that will source credentials from the Amazon EC2 Instance Metadata Service.

import { fromInstanceMetadata } from "@aws-sdk/credential-providers"; // ES6 import
// const { fromInstanceMetadata } = require("@aws-sdk/credential-providers"); // CommonJS import

const client = new FooClient({
  credentials: fromInstanceMetadata({
    maxRetries: 3, // Optional
    timeout: 0, // Optional
  }),
});

v2: ECSCredentials or RemoteCredentials

v3: fromContainerMetadata. Creates a credential provider that will source credentials from the Amazon ECS Container Metadata Service.

import { fromContainerMetadata } from "@aws-sdk/credential-providers"; // ES6 import

const client = new FooClient({
  credentials: fromContainerMetadata({
    maxRetries: 3, // Optional
    timeout: 0, // Optional
  }),
});

v2: FileSystemCredentials. Represents credentials from a JSON file on disk.

v3: Deprecated. You can explicitly read the JSON file and supply to the client. Please open a feature request to us if you need it.

v2: SAMLCredentials Represents credentials retrieved from STS SAML support.

v3: Not available. Please open a feature request to us if you need it.

v2: SharedIniFileCredentials

v3: fromIni

import { fromIni } from "@aws-sdk/credential-providers";
// const { fromIni } from("@aws-sdk/credential-providers");

const client = new FooClient({
  credentials: fromIni({
    configFilepath: "~/.aws/config", // Optional
    filepath: "~/.aws/credentials", // Optional
    mfaCodeProvider: async (mfaSerial) => {
      // implement a pop-up asking for MFA code
      return "some_code";
    }, // Optional
    profile: "default", // Optional
    clientConfig: { region }, // Optional
  }),
});

v2: TokenFileWebIdentityCredentials

v3: fromTokenFile

import { fromTokenFile } from "@aws-sdk/credential-providers"; // ES6 import
// const { fromTokenFile } from("@aws-sdk/credential-providers"); // CommonJS import

const client = new FooClient({
  credentials: fromTokenFile({
    // Optional. If skipped, read from `AWS_ROLE_ARN` environmental variable
    roleArn: "arn:xxxx",
    // Optional. If skipped, read from `AWS_ROLE_SESSION_NAME` environmental variable
    roleSessionName: "session:a",
    // Optional. STS client config to make the assume role request.
    clientConfig: { region },
  }),
});

v2: WebIdentityCredentials

v3: fromWebToken

import { fromWebToken } from "@aws-sdk/credential-providers"; // ES6 import
// const { fromWebToken } from("@aws-sdk/credential-providers"); // CommonJS import

const client = new FooClient({
  credentials: fromWebToken({
    // Optional. If skipped, read from `AWS_ROLE_ARN` environmental variable
    roleArn: "arn:xxxx",
    // Optional. If skipped, read from `AWS_ROLE_SESSION_NAME` environmental variable
    roleSessionName: "session:a",
    // Optional. STS client config to make the assume role request.
    clientConfig: { region },
  }),
});