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

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

Overview

Represents credentials retrieved from STS Web Identity Federation using the Amazon Cognito Identity service.

By default this provider gets credentials using the AWS.CognitoIdentity.getCredentialsForIdentity() service operation, which requires either an IdentityId or an IdentityPoolId (Amazon Cognito Identity Pool ID), which is used to call AWS.CognitoIdentity.getId() to obtain an IdentityId. If the identity or identity pool is not configured in the Amazon Cognito Console to use IAM roles with the appropriate permissions, then additionally a RoleArn is required containing the ARN of the IAM trust policy for the Amazon Cognito role that the user will log into. If a RoleArn is provided, then this provider gets credentials using the AWS.STS.assumeRoleWithWebIdentity() service operation, after first getting an Open ID token from AWS.CognitoIdentity.getOpenIdToken().

In addition, if this credential provider is used to provide authenticated login, the Logins map may be set to the tokens provided by the respective identity providers. See constructor() for an example on creating a credentials object with proper property values.

Refreshing Credentials from Identity Service

In addition to AWS credentials expiring after a given amount of time, the login token from the identity provider will also expire. Once this token expires, it will not be usable to refresh AWS credentials, and another token will be needed. The SDK does not manage refreshing of the token value, but this can be done through a "refresh token" supported by most identity providers. Consult the documentation for the identity provider for refreshing tokens. Once the refreshed token is acquired, you should make sure to update this new token in the credentials object's params property. The following code will update the WebIdentityToken, assuming you have retrieved an updated token from the identity provider:

AWS.config.credentials.params.Logins['graph.facebook.com'] = updatedToken;

Future calls to credentials.refresh() will now use the new token.

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.CognitoIdentityCredentials(params, clientConfig) ⇒ void

Note:

If a region is not provided in the global AWS.config, or specified in the clientConfig to the CognitoIdentityCredentials constructor, you may encounter a 'Missing credentials in config' error when calling making a service call.

Creates a new credentials object.

Examples:

Creating a new credentials object

AWS.config.credentials = new AWS.CognitoIdentityCredentials({

  // either IdentityPoolId or IdentityId is required
  // See the IdentityPoolId param for AWS.CognitoIdentity.getID (linked below)
  // See the IdentityId param for AWS.CognitoIdentity.getCredentialsForIdentity
  // or AWS.CognitoIdentity.getOpenIdToken (linked below)
  IdentityPoolId: 'us-east-1:1699ebc0-7900-4099-b910-2df94f52a030',
  IdentityId: 'us-east-1:128d0a74-c82f-4553-916d-90053e4a8b0f'

  // optional, only necessary when the identity pool is not configured
  // to use IAM roles in the Amazon Cognito Console
  // See the RoleArn param for AWS.STS.assumeRoleWithWebIdentity (linked below)
  RoleArn: 'arn:aws:iam::1234567890:role/MYAPP-CognitoIdentity',

  // optional tokens, used for authenticated login
  // See the Logins param for AWS.CognitoIdentity.getID (linked below)
  Logins: {
    'graph.facebook.com': 'FBTOKEN',
    'www.amazon.com': 'AMAZONTOKEN',
    'accounts.google.com': 'GOOGLETOKEN',
    'api.twitter.com': 'TWITTERTOKEN',
    'www.digits.com': 'DIGITSTOKEN'
  },

  // optional name, defaults to web-identity
  // See the RoleSessionName param for AWS.STS.assumeRoleWithWebIdentity (linked below)
  RoleSessionName: 'web',

  // optional, only necessary when application runs in a browser
  // and multiple users are signed in at once, used for caching
  LoginId: 'example@gmail.com'

}, {
   // optionally provide configuration to apply to the underlying service clients
   // if configuration is not provided, then configuration will be pulled from AWS.config

   // region should match the region your identity pool is located in
   region: 'us-east-1',

   // specify timeout options
   httpOptions: {
     timeout: 100
   }
});

See Also:

Property Details

data ⇒ map (readwrite)

Returns the raw data response from the call to AWS.CognitoIdentity.getCredentialsForIdentity(), or AWS.STS.assumeRoleWithWebIdentity(). Use this if you want to get access to other properties from the response.

Returns:

identityId ⇒ String (readwrite)

Returns the Cognito ID returned by the last call to AWS.CognitoIdentity.getOpenIdToken(). This ID represents the actual final resolved identity ID from Amazon Cognito.

Returns:

params ⇒ map (readwrite)

Returns the map of params passed to AWS.CognitoIdentity.getId(), AWS.CognitoIdentity.getOpenIdToken(), and AWS.STS.assumeRoleWithWebIdentity(). To update the token, set the params.WebIdentityToken property.

Returns:

Method Details

clearCachedId() ⇒ void

Clears the cached Cognito ID associated with the currently configured identity pool ID. Use this to manually invalidate your cache if the identity pool ID was deleted.

refresh(callback) ⇒ void

Refreshes credentials using AWS.CognitoIdentity.getCredentialsForIdentity(), or AWS.STS.assumeRoleWithWebIdentity().

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: