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.Credentials

Inherits:
Object
  • Object
show all
Defined in:
lib/credentials.js

Overview

Represents your AWS security credentials, specifically the accessKeyId, secretAccessKey, and optional sessionToken. Creating a Credentials object allows you to pass around your security information to configuration and service objects.

Note that this class typically does not need to be constructed manually, as the AWS.Config and AWS.Service classes both accept simple options hashes with the three keys. These structures will be converted into Credentials objects automatically.

Expiring and Refreshing Credentials

Occasionally credentials can expire in the middle of a long-running application. In this case, the SDK will automatically attempt to refresh the credentials from the storage location if the Credentials class implements the refresh() method.

If you are implementing a credential storage location, you will want to create a subclass of the Credentials class and override the refresh() method. This method allows credentials to be retrieved from the backing store, be it a file system, database, or some network storage. The method should reset the credential attributes on the object.

Constructor Summary collapse

Property Summary collapse

Method Summary collapse

Constructor Details

new AWS.Credentials(accessKeyId, secretAccessKey, sessionToken = null) ⇒ void new AWS.Credentials(options) ⇒ void

A credentials object can be created using positional arguments or an options hash.

Overloads:

  • new AWS.Credentials(accessKeyId, secretAccessKey, sessionToken = null) ⇒ void

    Creates a Credentials object with a given set of credential information as positional arguments.

    Examples:

    Create a credentials object with AWS credentials

    var creds = new AWS.Credentials('akid', 'secret', 'session');

    Parameters:

    • accessKeyId (String) —

      the AWS access key ID

    • secretAccessKey (String) —

      the AWS secret access key

    • sessionToken (String) (defaults to: null) —

      the optional AWS session token

  • new AWS.Credentials(options) ⇒ void

    Creates a Credentials object with a given set of credential information as an options hash.

    Examples:

    Create a credentials object with AWS credentials

    var creds = new AWS.Credentials({
  accessKeyId: 'akid', secretAccessKey: 'secret', sessionToken: 'session'
});

    Options Hash (options):

    • accessKeyId (String) —

      the AWS access key ID

    • secretAccessKey (String) —

      the AWS secret access key

    • sessionToken (String) —

      the optional AWS session token

Property Details

accessKeyId ⇒ String (readwrite)

Returns the AWS access key ID.

Returns:

  • (String) —

    the AWS access key ID

expired ⇒ Boolean (readwrite)

Returns whether the credentials have been expired and require a refresh. Used in conjunction with expireTime.

Returns:

  • (Boolean) —

    whether the credentials have been expired and require a refresh. Used in conjunction with expireTime.

expireTime ⇒ Date (readwrite)

Returns a time when credentials should be considered expired. Used in conjunction with expired.

Returns:

  • (Date) —

    a time when credentials should be considered expired. Used in conjunction with expired.

expiryWindow ⇒ Integer, Number (static, readwrite)

Default Value:

AWS.Credentials.expiryWindow = 15

secretAccessKey ⇒ String (readwrite)

Returns the AWS secret access key.

Returns:

  • (String) —

    the AWS secret access key

sessionToken ⇒ String (readwrite)

Returns an optional AWS session token.

Returns:

  • (String) —

    an optional AWS session token

Method Details

get(callback) ⇒ void

Gets the existing credentials, refreshing them if they are not yet loaded or have expired. Users should call this method before using refresh(), as this will not attempt to reload credentials when they are already loaded into the object.

Callback (callback):

  • function(err) { ... }

    When this callback is called with no error, it means either credentials do not need to be refreshed or refreshed 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

getPromise() ⇒ Promise

Returns a 'thenable' promise. Gets the existing credentials, refreshing them if they are not yet loaded or have expired. Users should call this method before using refresh(), as this will not attempt to reload credentials when they are already loaded into the object.

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 getPromise method.

var promise = credProvider.getPromise();
promise.then(function() { ... }, function(err) { ... });

Callbacks:

  • function() { ... }

    Called if the promise is fulfilled. When this callback is called, it means either credentials do not need to be refreshed or refreshed credentials information has been loaded into the object (as the accessKeyId, secretAccessKey, and sessionToken properties).

  • function(err) { ... }

    Called if the promise is rejected.

    Parameters:

    • err (Error) —

      if an error occurred, this value will be filled

Returns:

  • (Promise) —

    A promise that represents the state of the get call.

needsRefresh() ⇒ Boolean

Note:

Subclasses should override this method to provide custom refresh logic.

Returns whether the credentials object should call refresh().

Returns:

  • (Boolean) —

    whether the credentials object should call refresh()

refresh(callback) ⇒ void

Note:

Subclasses should override this class to reset the accessKeyId, secretAccessKey and optional sessionToken on the credentials object and then call the callback with any error information.

Refreshes the credentials. Users should call get() before attempting to forcibly refresh credentials.

Callback (callback):

  • function(err) { ... }

    When this callback is called with no error, it means refreshed 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:

refreshPromise() ⇒ Promise

Returns a 'thenable' promise. Refreshes the credentials. Users should call get() before attempting to forcibly refresh credentials.

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 refreshPromise method.

var promise = credProvider.refreshPromise();
promise.then(function() { ... }, function(err) { ... });

Callbacks:

  • function() { ... }

    Called if the promise is fulfilled. When this callback is called, it means refreshed credentials information has been loaded into the object (as the accessKeyId, secretAccessKey, and sessionToken properties).

  • function(err) { ... }

    Called if the promise is rejected.

    Parameters:

    • err (Error) —

      if an error occurred, this value will be filled

Returns:

  • (Promise) —

    A promise that represents the state of the refresh call.