We announced the upcoming end-of-support for AWS SDK for JavaScript v2.
We recommend that you migrate to AWS SDK for JavaScript v3. For dates, additional details, and information on how to migrate, please refer to the linked announcement.

Class: AWS.ChainableTemporaryCredentials

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

Overview

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.

For example, if the application should use RoleA, which must be assumed from RoleB, and the environment provides credentials which can assume RoleB, then AWS.ChainableTemporaryCredentials must be used to support refreshing the temporary credentials for RoleA:

var roleACreds = new AWS.ChainableTemporaryCredentials({
  params: {RoleArn: 'RoleA'},
  masterCredentials: new AWS.ChainableTemporaryCredentials({
    params: {RoleArn: 'RoleB'},
    masterCredentials: new AWS.EnvironmentCredentials('AWS')
  })
});

If AWS.TemporaryCredentials had been used in the previous example, roleACreds would fail to refresh because roleACreds would use the environment credentials for the AssumeRole request.

Another difference is that AWS.ChainableTemporaryCredentials creates the STS service instance during instantiation while AWS.TemporaryCredentials creates the STS service instance during the first refresh. Creating the service instance during instantiation effectively captures the master credentials from the global config, so that subsequent changes to the global config do not affect the master credentials used to refresh the temporary credentials.

This allows an instance of AWS.ChainableTemporaryCredentials to be assigned to AWS.config.credentials:

var envCreds = new AWS.EnvironmentCredentials('AWS');
AWS.config.credentials = envCreds;
// masterCredentials will be envCreds
AWS.config.credentials = new AWS.ChainableTemporaryCredentials({
  params: {RoleArn: '...'}
});

Similarly, to use the CredentialProviderChain's default providers as the master credentials, simply create a new instance of AWS.ChainableTemporaryCredentials:

AWS.config.credentials = new ChainableTemporaryCredentials({
  params: {RoleArn: '...'}
});

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

Constructor Details

new AWS.ChainableTemporaryCredentials(options) ⇒ void

Creates a new temporary credentials object.

Examples:

Creating a new credentials object for generic temporary credentials

AWS.config.credentials = new AWS.ChainableTemporaryCredentials();

Creating a new credentials object for an IAM role

AWS.config.credentials = new AWS.ChainableTemporaryCredentials({
  params: {
    RoleArn: 'arn:aws:iam::1234567890:role/TemporaryCredentials'
  }
});

Parameters:

  • options (map) —

    a set of options

Options Hash (options):

  • params (map) — default: {} —

    a map of options that are passed to the AWS.STS.assumeRole() or AWS.STS.getSessionToken() operations. If a RoleArn parameter is passed in, credentials will be based on the IAM role. If a SerialNumber parameter is passed in, AWS.ChainableTemporaryCredentials.tokenCodeFn must also be passed in or an error will be thrown.

  • masterCredentials (AWS.Credentials) —

    the master credentials used to get and refresh temporary credentials from AWS STS. By default, AWS.config.credentials or AWS.config.credentialProvider will be used.

  • tokenCodeFn (Function) — default: null —

    Function to provide TokenCode, if SerialNumber is provided for profile in AWS.ChainableTemporaryCredentials.params. Function is called with value of SerialNumber and callback, and should provide the TokenCode or an error to the callback in the format callback(err, token).

See Also:

Property Details

service ⇒ AWS.STS (readwrite)

Returns the STS service instance used to get and refresh temporary credentials from AWS STS.

Returns:

  • (AWS.STS) —

    the STS service instance used to get and refresh temporary credentials from AWS STS.

Method Details

refresh(callback) ⇒ void

Refreshes credentials using AWS.STS.assumeRole() or AWS.STS.getSessionToken(), depending on whether an IAM role ARN was passed to the credentials constructor().

Callback (callback):

  • function(err) { ... }

    Called when the STS service responds (or fails). When this callback is called with no error, it means that the credentials information has been loaded into the object (as the accessKeyId, secretAccessKey, and sessionToken properties).

    Parameters:

    • err (Error) —

      if an error occurred, this value will be filled

See Also: