Using Amazon Cognito Identity to authenticate users - Amazon SDK for JavaScript
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.

The Amazon SDK for JavaScript V3 API Reference Guide describes in detail all the API operations for the Amazon SDK for JavaScript version 3 (V3).

Starting October 1, 2022, Amazon SDK for JavaScript (v3) will end support for Internet Explorer 11 (IE 11). For details, see Announcing the end of support for Internet Explorer 11 in the Amazon SDK for JavaScript (v3).

Using Amazon Cognito Identity to authenticate users

The recommended way to obtain Amazon credentials for your browser scripts is to use the Amazon Cognito Identity credentials client CognitoIdentityClient. Amazon Cognito enables authentication of users through third-party identity providers.

To use Amazon Cognito Identity, you must first create an identity pool in the Amazon Cognito console. An identity pool represents the group of identities that your application provides to your users. The identities given to users uniquely identify each user account. Amazon Cognito identities are not credentials. They are exchanged for credentials using web identity federation support in Amazon Security Token Service (Amazon STS).

Amazon Cognito helps you manage the abstraction of identities across multiple identity providers. The identity that is loaded is then exchanged for credentials in Amazon STS.

Configuring the Amazon Cognito Identity credentials object

If you have not yet created one, create an identity pool to use with your browser scripts in the Amazon Cognito console before you configure your Amazon Cognito client. Create and associate both authenticated and unauthenticated IAM roles for your identity pool. For more information, see

Unauthenticated users don't have their identity verified, making this role appropriate for guest users of your app or in cases when it doesn't matter if users have their identities verified. Authenticated users log in to your application through a third-party identity provider that verifies their identities. Make sure you scope the permissions of resources appropriately so you don't grant access to them from unauthenticated users.

After you configure an identity pool, use the fromCognitoIdentityPool method from the @aws-sdk/credential-providers to retrieve the cendentials from the identity pool. This is shown in the following example of creating an Amazon S3 client in the us-west-2 Amazon Region for users in the IDENTITY_POOL_ID identity pool.

// Import required AWS SDK clients and command for Node.js import {S3Client} from "@aws-sdk/client-s3"; import {fromCognitoIdentityPool} from "@aws-sdk/credential-providers"; const REGION = AWS_REGION const s3Client = new S3Client({ region: REGION, credentials: fromCognitoIdentityPool({ clientConfig: { region: REGION }, // Configure the underlying CognitoIdentityClient. identityPoolId: 'IDENTITY_POOL_ID', logins: { // Optional tokens, used for authenticated login. }, }) });

The optional logins property is a map of identity provider names to the identity tokens for those providers. How you get the token from your identity provider depends on the provider you use. For example, if you are using an Amazon Cognito user pool as your authentication provider, you could use a method similar to the one below.

// Get the Amazon Cognito ID token for the user. 'getToken()' below. let idToken = getToken(); let COGNITO_ID = "COGNITO_ID"; // 'COGNITO_ID' has the format '' let loginData = { [COGNITO_ID]: idToken, }; const s3Client = new S3Client({ region: REGION, credentials: fromCognitoIdentityPool({ clientConfig: { region: REGION }, // Configure the underlying CognitoIdentityClient. identityPoolId: 'IDENTITY_POOL_ID', logins: loginData }) }); // Strips the token ID from the URL after authentication. window.getToken = function () { var idtoken = window.location.href; var idtoken1 = idtoken.split("=")[1]; var idtoken2 = idtoken1.split("&")[0]; var idtoken3 = idtoken2.split("&")[0]; return idtoken3; };

Switching Unauthenticated Users to Authenticated Users

Amazon Cognito supports both authenticated and unauthenticated users. Unauthenticated users receive access to your resources even if they aren't logged in with any of your identity providers. This degree of access is useful to display content to users prior to logging in. Each unauthenticated user has a unique identity in Amazon Cognito even though they have not been individually logged in and authenticated.

Initially Unauthenticated User

Users typically start with the unauthenticated role, for which you set the credentials property of your configuration object without a logins property. In this case, your default credentials might look like the following:

// Import the required Amazon SDK for JavaScript v3 modules. import {fromCognitoIdentityPool} from "@aws-sdk/credential-providers"; // Set the default credentials. const creds = new fromCognitoIdentityPool({ IdentityPoolId: "IDENTITY_POOL_ID", clientConfig({ region: REGION }) // Configure the underlying CognitoIdentityClient. });

Switch to Authenticated User

When an unauthenticated user logs in to an identity provider and you have a token, you can switch the user from unauthenticated to authenticated by calling a custom function that updates the credentials object and adds the logins token.

// Called when an identity provider has a token for a logged in user function userLoggedIn(providerName, token) { creds.params.Logins = creds.params.logins || {}; creds.params.Logins[providerName] = token; // Expire credentials to refresh them on the next request creds.expired = true; }