Class: AWS.Credentials

Inherits:
Object
  • Object
show all
Defined in:
lib/config.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.

Direct Known Subclasses

AWS.CredentialProviderChain, AWS.EC2MetadataCredentials, AWS.EnvironmentCredentials, AWS.FileSystemCredentials

Constructor Summary (collapse)

Property Summary (collapse)

Method Summary (collapse)

Constructor Details

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

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

Overloads:

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

    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)

    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

(String) accessKeyId (readwrite)

The AWS access key ID

Returns:

  • (String) —

    the AWS access key ID

(Boolean) expired (readwrite)

Whether the credentials have been expired and require a refresh

Returns:

  • (Boolean) —

    whether the credentials have been expired and require a refresh

(String) secretAccessKey (readwrite)

The AWS secret access key

Returns:

  • (String) —

    the AWS secret access key

(String) sessionToken (readwrite)

An optional AWS session token

Returns:

  • (String) —

    an optional AWS session token

Method Details

(void) get(callback)

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) { ... }

    Called when the instance metadata 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

(Boolean) needsRefresh()

Note:

Subclasses should override this method to provide custom refresh logic.

Whether the credentials object should call refresh()

Returns:

  • (Boolean) —

    whether the credentials object should call refresh()

(void) refresh(callback)

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) { ... }

    Called when the instance metadata 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: