AWS.ChainableTemporaryCredentials — AWS SDK for JavaScript (original) (raw)

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.

Overview

Represents temporary credentials retrieved from AWS.STS. Without any extra parameters, credentials will be fetched from theAWS.STS.getSessionToken() operation. If an IAM role is provided, theAWS.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 Summarycollapse

• new AWS.ChainableTemporaryCredentials(options) ⇒ void constructor
  Creates a new temporary credentials object.

Property Summarycollapse

• service ⇒ AWS.STS readwrite
  The STS service instance used to get and refresh temporary credentials from AWS STS.

Properties inherited from AWS.Credentials

expired, expireTime, accessKeyId, secretAccessKey, sessionToken, expiryWindow

Method Summarycollapse

• refresh(callback) ⇒ void

Methods inherited from AWS.Credentials

needsRefresh, get, getPromise, refreshPromise

Constructor Details

new AWS.ChainableTemporaryCredentials(options) ⇒ void

Creates a new temporary credentials object.

Property Details

service ⇒ AWS.STS

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

Method Details

refresh(callback) ⇒ void