You are viewing the documentation for an older major version of the AWS SDK for JavaScript.
The modular AWS SDK for JavaScript (v3), the latest major version of AWS SDK for JavaScript, is now stable and recommended for general use. For more information, see the Migration Guide and API Reference.

Class: AWS.CredentialProviderChain

Inherits:
AWS.Credentials show all
Defined in:
lib/credentials/credential_provider_chain.js

Overview

Creates a credential provider chain that searches for AWS credentials in a list of credential providers specified by the providers property.

By default, the chain will use the defaultProviders to resolve credentials. These providers will look in the environment using the AWS.EnvironmentCredentials class with the 'AWS' and 'AMAZON' prefixes.

Setting Providers

Each provider in the providers list should be a function that returns a AWS.Credentials object, or a hardcoded credentials object. The function form allows for delayed execution of the credential construction.

Resolving Credentials from a Chain

Call resolve() to return the first valid credential object that can be loaded by the provider chain.

For example, to resolve a chain with a custom provider that checks a file on disk after the set of defaultProviders:

var diskProvider = new AWS.FileSystemCredentials('./creds.json');
var chain = new AWS.CredentialProviderChain();
chain.providers.push(diskProvider);
chain.resolve();

The above code will return the diskProvider object if the file contains credentials and the defaultProviders do not contain any credential settings.

Constructor Summary collapse

Property Summary collapse

Properties inherited from AWS.Credentials

expired, expireTime, accessKeyId, secretAccessKey, sessionToken, expiryWindow

Method Summary collapse

Methods inherited from AWS.Credentials

needsRefresh, get, getPromise, refreshPromise, refresh

Constructor Details

new AWS.CredentialProviderChain(providers) ⇒ void

Creates a new CredentialProviderChain with a default set of providers specified by defaultProviders.

Property Details

defaultProviders ⇒ Object (static, readwrite)

The default set of providers used by a vanilla CredentialProviderChain.

In the browser:

AWS.CredentialProviderChain.defaultProviders = []

In Node.js:

AWS.CredentialProviderChain.defaultProviders = [
  function () { return new AWS.EnvironmentCredentials('AWS'); },
  function () { return new AWS.EnvironmentCredentials('AMAZON'); },
  function () { return new AWS.SharedIniFileCredentials(); },
  function () { return new AWS.ECSCredentials(); },
  function () { return new AWS.ProcessCredentials(); },
  function () { return new AWS.TokenFileWebIdentityCredentials(); },
  function () { return new AWS.EC2MetadataCredentials() }
]

Default Value:

AWS.CredentialProviderChain.defaultProviders = []

providers ⇒ Array<AWS.Credentials, Function> (readwrite)

Returns a list of credentials objects or functions that return credentials objects. If the provider is a function, the function will be executed lazily when the provider needs to be checked for valid credentials. By default, this object will be set to the defaultProviders.

Returns:

  • (Array<AWS.Credentials, Function>) —

    a list of credentials objects or functions that return credentials objects. If the provider is a function, the function will be executed lazily when the provider needs to be checked for valid credentials. By default, this object will be set to the defaultProviders.

See Also:

Method Details

resolve(callback) ⇒ AWS.CredentialProviderChain

Resolves the provider chain by searching for the first set of credentials in providers.

Callback (callback):

  • function(err, credentials) { ... }

    Called when the provider resolves the chain to a credentials object or null if no credentials can be found.

    Parameters:

    • err (Error) —

      the error object returned if no credentials are found.

    • credentials (AWS.Credentials) —

      the credentials object resolved by the provider chain.

Returns:

resolvePromise() ⇒ Promise

Returns a 'thenable' promise. Resolves the provider chain by searching for the first set of credentials in providers.

Two callbacks can be provided to the then method on the returned promise. The first callback will be called if the promise is fulfilled, and the second callback will be called if the promise is rejected.

Examples:

Calling the resolvePromise method.

var promise = chain.resolvePromise();
promise.then(function(credentials) { ... }, function(err) { ... });

Callbacks:

  • function(credentials) { ... }

    Called if the promise is fulfilled and the provider resolves the chain to a credentials object

    Parameters:

    • credentials (AWS.Credentials) —

      the credentials object resolved by the provider chain.

  • function(error) { ... }

    Called if the promise is rejected.

    Parameters:

    • err (Error) —

      the error object returned if no credentials are found.

Returns:

  • (Promise) —

    A promise that represents the state of the resolve method call.