amazon-cognito-identity-js
Advanced tools
The amazon-cognito-identity-js package provides JavaScript developers with an easy way to integrate Amazon Cognito's user pool functionality into their applications. This includes user authentication, session management, and other user identity features.
User Authentication
Authenticate users through Amazon Cognito User Pools. This includes signing in users, handling session tokens, and managing user credentials.
AuthenticationDetails, CognitoUserPool, CognitoUserUser Registration
Register new users to the Cognito User Pool and confirm their accounts. This also includes handling custom attributes for user accounts.
CognitoUserPool, CognitoUserAttributePassword Management
Manage user passwords, including the ability to change a password, initiate a forgot password flow, and confirm a new password with a verification code.
CognitoUserSession Handling
Handle user sessions, including refreshing tokens and verifying the validity of a session.
CognitoUserSessionMulti-Factor Authentication (MFA)
Support for Multi-Factor Authentication, enabling additional security for user sign-in.
CognitoUseraws-amplify is a comprehensive library from AWS that includes support for Cognito among other AWS services. It is more feature-rich and provides a higher level abstraction compared to amazon-cognito-identity-js.
auth0-js is a client-side library for Auth0, which is a flexible, drop-in solution to add authentication and authorization services to your applications. It is similar in providing user authentication but is not limited to AWS services.
passport is a middleware for Node.js that can be used to implement user authentication with a wide variety of strategies, including OAuth, OpenID, and others. It is more generic and can be used with different backends, not just Cognito.
You can now use Amazon Cognito to easily add user sign-up and sign-in to your mobile and web apps. Your User Pool in Amazon Cognito is a fully managed user directory that can scale to hundreds of millions of users, so you don't have to worry about building, securing, and scaling a solution to handle user management and authentication.
We welcome developer feedback on this project. You can reach us by creating an issue on the GitHub repository or posting to the Amazon Cognito Identity forums and the below blog post:
For an overview of the Cognito authentication flow, refer to the following blog post:
The Amazon Cognito Identity SDK for JavaScript allows JavaScript enabled applications to sign-up users, authenticate users, view, delete, and update user attributes within the Amazon Cognito Identity service. Other functionality includes password changes for authenticated users and initiating and completing forgot password flows for unauthenticated users.
Your users will benefit from a number of security features including SMS-based Multi-Factor Authentication (MFA) and account verification via phone or email. The password features use the Secure Remote Password (SRP) protocol to avoid sending cleartext passwords over the wire.
The Amazon Cognito Identity SDK for JavaScript depends on:
CognitoIdentityServiceProvider service from the AWS SDK for JavaScriptThere are two ways to install the Amazon Cognito Identity SDK for JavaScript and its dependencies, depending on your project setup and experience with modern JavaScript build tools:
Download each JavaScript library and include them in your HTML, or
Install the dependencies with npm and use a bundler like webpack.
This method is simpler and does not require additional tools, but may have worse performance due to the browser having to download multiple files.
Download each of the following JavaScript files for the required libraries and place them in your project:
The Amazon Cognito AWS SDK for JavaScript, from /dist/aws-cognito-sdk.min.js
Note that the Amazon Cognito AWS SDK for JavaScript is just a slimmed down version of the AWS
Javascript SDK namespaced as AWSCognito instead of AWS. It references only the Amazon
Cognito Identity service.
The Amazon Cognito Identity SDK for JavaScript, from /dist/amazon-cognito-identity.min.js
Optionally, to use other AWS services, include a build of the AWS SDK for JavaScript.
Include all of the files in your HTML page before calling any Amazon Cognito Identity SDK APIs:
<script src="/path/to/aws-cognito-sdk.min.js"></script>
<script src="/path/to/amazon-cognito-identity.min.js"></script>
<!-- optional: only if you use other AWS services -->
<script src="/path/to/aws-sdk-2.6.10.js"></script>
Webpack is a popular JavaScript bundling and optimization tool, it has many configuration features that can build your source JavaScript into one or more files for distribution. The following is a quick setup guide with specific notes for using the Amazon Cognito Identity SDK for JavaScript with it, but there are many more ways it can be used, see the Webpack site, and in particular the configuration documentation
Note that webpack expects your source files to be structured as CommonJS (Node.js-style) modules (or ECMAScript 2015 modules if you are using a transpiler such as Babel.) If your project is not already using modules you may wish to use Webpack's module shimming features to ease migration.
Install Node.js on your development machine (this will not be needed on your server.)
In your project add a package.json, either use npm init or the minimal:
{
"private": true
}
Install the Amazon Cognito Identity SDK for JavaScript and the Webpack tool into your project with npm (the Node
Package Manager, which is installed with Node.js):
> npm install --save-dev webpack json-loader
> npm install --save amazon-cognito-identity-js
These will add a node_modules directory containing these tools and dependencies into your
project, you will probably want to exclude this directory from source control. Adding the --save
parameters will update the package.json file with instructions on what should be installed, so
you can simply call npm install without any parameters to recreate this folder later.
Create the configuration file for webpack, named webpack.config.js:
module.exports = {
// Example setup for your project:
// The entry module that requires or imports the rest of your project.
// Must start with `./`!
entry: './src/entry',
// Place output files in `./dist/my-app.js`
output: {
path: 'dist',
filename: 'my-app.js'
},
module: {
loaders: [
{
test: /\.json$/,
loader: 'json'
}
]
}
};
Add the following into your package.json
{
"scripts": {
"build": "webpack"
}
}
Build your application bundle with npm run build
See Using NPM and Webpack for more information on NPM.
npm install --save amazon-cognito-identity-js
npm install -g react-native-cli
react-native link amazon-cognito-identity-js
The Amazon Cognito Identity SDK for JavaScript requires two configuration values from your AWS Account in order to access your Cognito User Pool:
us-east-1_aB12cDe347ghr5379orhbo88d52vphda6s9
The AWS Console for Cognito User Pools can be used to get or create these values.
If you will be using Cognito Federated Identity to provide access to your AWS resources or Cognito Sync you will also need the Id of a Cognito Identity Pool that will accept logins from the above Cognito User Pool and App, i.e. us-east-1:85156295-afa8-482c-8933-1371f8b3b145.
Note that the various errors returned by the service are valid JSON so one can access the different exception types (err.code) and status codes (err.statusCode).
For an example using babel-webpack of a React setup, see babel-webpack example.
For a working example using angular, see cognito-angular2-quickstart.
For a working example using ember.js, see:
If you are having issues when using Aurelia, please see the following Stack Overflow post.
The usage examples below use the unqualified names for types in the Amazon Cognito Identity SDK for JavaScript. Remember to import or qualify access to any of these types:
// When using loose Javascript files:
var CognitoUserPool = AmazonCognitoIdentity.CognitoUserPool;
// Under the original name:
var CognitoUserPool = AWSCognito.CognitoIdentityServiceProvider.CognitoUserPool;
// Modules, e.g. Webpack:
var AmazonCognitoIdentity = require('amazon-cognito-identity-js');
var CognitoUserPool = AmazonCognitoIdentity.CognitoUserPool;
// ES Modules, e.g. transpiling with Babel
import { CognitoUserPool, CognitoUserAttribute, CognitoUser } from 'amazon-cognito-identity-js';
Use case 1. Registering a user with the application. One needs to create a CognitoUserPool object by providing a UserPoolId and a ClientId and signing up by using a username, password, attribute list, and validation data.
var poolData = {
UserPoolId : '...', // Your user pool id here
ClientId : '...' // Your client id here
};
var userPool = new AWSCognito.CognitoIdentityServiceProvider.CognitoUserPool(poolData);
var attributeList = [];
var dataEmail = {
Name : 'email',
Value : 'email@mydomain.com'
};
var dataPhoneNumber = {
Name : 'phone_number',
Value : '+15555555555'
};
var attributeEmail = new AWSCognito.CognitoIdentityServiceProvider.CognitoUserAttribute(dataEmail);
var attributePhoneNumber = new AWSCognito.CognitoIdentityServiceProvider.CognitoUserAttribute(dataPhoneNumber);
attributeList.push(attributeEmail);
attributeList.push(attributePhoneNumber);
userPool.signUp('username', 'password', attributeList, null, function(err, result){
if (err) {
alert(err);
return;
}
cognitoUser = result.user;
console.log('user name is ' + cognitoUser.getUsername());
});
Use case 2. Confirming a registered, unauthenticated user using a confirmation code received via SMS.
var poolData = {
UserPoolId : '...', // Your user pool id here
ClientId : '...' // Your client id here
};
var userPool = new AWSCognito.CognitoIdentityServiceProvider.CognitoUserPool(poolData);
var userData = {
Username : 'username',
Pool : userPool
};
var cognitoUser = new AWSCognito.CognitoIdentityServiceProvider.CognitoUser(userData);
cognitoUser.confirmRegistration('123456', true, function(err, result) {
if (err) {
alert(err);
return;
}
console.log('call result: ' + result);
});
Use case 3. Resending a confirmation code via SMS for confirming registration for a unauthenticated user.
cognitoUser.resendConfirmationCode(function(err, result) {
if (err) {
alert(err);
return;
}
console.log('call result: ' + result);
});
Use case 4. Authenticating a user and establishing a user session with the Amazon Cognito Identity service.
var authenticationData = {
Username : 'username',
Password : 'password',
};
var authenticationDetails = new AWSCognito.CognitoIdentityServiceProvider.AuthenticationDetails(authenticationData);
var poolData = {
UserPoolId : '...', // Your user pool id here
ClientId : '...' // Your client id here
};
var userPool = new AWSCognito.CognitoIdentityServiceProvider.CognitoUserPool(poolData);
var userData = {
Username : 'username',
Pool : userPool
};
var cognitoUser = new AWSCognito.CognitoIdentityServiceProvider.CognitoUser(userData);
cognitoUser.authenticateUser(authenticationDetails, {
onSuccess: function (result) {
console.log('access token + ' + result.getAccessToken().getJwtToken());
//POTENTIAL: Region needs to be set if not already set previously elsewhere.
AWS.config.region = '<region>';
AWS.config.credentials = new AWS.CognitoIdentityCredentials({
IdentityPoolId : '...', // your identity pool id here
Logins : {
// Change the key below according to the specific region your user pool is in.
'cognito-idp.<region>.amazonaws.com/<YOUR_USER_POOL_ID>' : result.getIdToken().getJwtToken()
}
});
//refreshes credentials using AWS.CognitoIdentity.getCredentialsForIdentity()
AWS.config.credentials.refresh((error) => {
if (error) {
console.error(error);
} else {
// Instantiate aws sdk service objects now that the credentials have been updated.
// example: var s3 = new AWS.S3();
console.log('Successfully logged!');
}
});
},
onFailure: function(err) {
alert(err);
},
});
Note that if device tracking is enabled for the user pool with a setting that user opt-in is required, you need to implement an onSuccess(result, userConfirmationNecessary) callback, collect user input and call either setDeviceStatusRemembered to remember the device or setDeviceStatusNotRemembered to not remember the device.
Note also that if CognitoUser.authenticateUser throws ReferenceError: navigator is not defined when running on Node.js, follow the instructions on the following Stack Overflow post.
Use case 5. Retrieve user attributes for an authenticated user.
cognitoUser.getUserAttributes(function(err, result) {
if (err) {
alert(err);
return;
}
for (i = 0; i < result.length; i++) {
console.log('attribute ' + result[i].getName() + ' has value ' + result[i].getValue());
}
});
Use case 6. Verify user attribute for an authenticated user.
Note that the inputVerificationCode method needs to be defined but does not need to actually do anything. If you would like the user to input the verification code on another page, you can set inputVerificationCode to null. If inputVerificationCode is null, onSuccess will be called immediately (assuming there is no error).
cognitoUser.getAttributeVerificationCode('email', {
onSuccess: function (result) {
console.log('call result: ' + result);
},
onFailure: function(err) {
alert(err);
},
inputVerificationCode: function() {
var verificationCode = prompt('Please input verification code: ' ,'');
cognitoUser.verifyAttribute('email', verificationCode, this);
}
});
Use case 7. Delete user attribute for an authenticated user.
var attributeList = [];
attributeList.push('nickname');
cognitoUser.deleteAttributes(attributeList, function(err, result) {
if (err) {
alert(err);
return;
}
console.log('call result: ' + result);
});
Use case 8. Update user attributes for an authenticated user.
var attributeList = [];
var attribute = {
Name : 'nickname',
Value : 'joe'
};
var attribute = new AWSCognito.CognitoIdentityServiceProvider.CognitoUserAttribute(attribute);
attributeList.push(attribute);
cognitoUser.updateAttributes(attributeList, function(err, result) {
if (err) {
alert(err);
return;
}
console.log('call result: ' + result);
});
Use case 9. Enabling MFA for a user on a pool that has an optional MFA setting for an authenticated user.
cognitoUser.enableMFA(function(err, result) {
if (err) {
alert(err);
return;
}
console.log('call result: ' + result);
});
Use case 10. Disabling MFA for a user on a pool that has an optional MFA setting for an authenticated user.
cognitoUser.disableMFA(function(err, result) {
if (err) {
alert(err);
return;
}
console.log('call result: ' + result);
});
Use case 11. Changing the current password for an authenticated user.
cognitoUser.changePassword('oldPassword', 'newPassword', function(err, result) {
if (err) {
alert(err);
return;
}
console.log('call result: ' + result);
});
Use case 12. Starting and completing a forgot password flow for an unauthenticated user.
cognitoUser.forgotPassword({
onSuccess: function (data) {
// successfully initiated reset password request
console.log('CodeDeliveryData from forgotPassword: ' + data);
},
onFailure: function(err) {
alert(err);
},
//Optional automatic callback
inputVerificationCode: function(data) {
console.log('Code sent to: ' + data);
var verificationCode = prompt('Please input verification code ' ,'');
var newPassword = prompt('Enter new password ' ,'');
cognitoUser.confirmPassword(verificationCode, newPassword, {
onSuccess() {
console.log('Password confirmed!');
},
onFailure(err) {
console.log('Password not confirmed!');
}
});
}
});
Use case 13. Deleting an authenticated user.
cognitoUser.deleteUser(function(err, result) {
if (err) {
alert(err);
return;
}
console.log('call result: ' + result);
});
Use case 14. Signing out from the application.
cognitoUser.signOut();
Use case 15. Global signout for an authenticated user(invalidates all issued tokens).
cognitoUser.globalSignOut(callback);
Use case 16. Retrieving the current user from local storage.
var poolData = {
UserPoolId : '...', // Your user pool id here
ClientId : '...' // Your client id here
};
var userPool = new AWSCognito.CognitoIdentityServiceProvider.CognitoUserPool(poolData);
var cognitoUser = userPool.getCurrentUser();
if (cognitoUser != null) {
cognitoUser.getSession(function(err, session) {
if (err) {
alert(err);
return;
}
console.log('session validity: ' + session.isValid());
// NOTE: getSession must be called to authenticate user before calling getUserAttributes
cognitoUser.getUserAttributes(function(err, attributes) {
if (err) {
// Handle error
} else {
// Do something with attributes
}
});
AWS.config.credentials = new AWS.CognitoIdentityCredentials({
IdentityPoolId : '...', // your identity pool id here
Logins : {
// Change the key below according to the specific region your user pool is in.
'cognito-idp.<region>.amazonaws.com/<YOUR_USER_POOL_ID>' : session.getIdToken().getJwtToken()
}
});
// Instantiate aws sdk service objects now that the credentials have been updated.
// example: var s3 = new AWS.S3();
});
}
Use case 17. Integrating User Pools with Cognito Identity.
var cognitoUser = userPool.getCurrentUser();
if (cognitoUser != null) {
cognitoUser.getSession(function(err, result) {
if (result) {
console.log('You are now logged in.');
// Add the User's Id Token to the Cognito credentials login map.
AWS.config.credentials = new AWS.CognitoIdentityCredentials({
IdentityPoolId: 'YOUR_IDENTITY_POOL_ID',
Logins: {
'cognito-idp.<region>.amazonaws.com/<YOUR_USER_POOL_ID>': result.getIdToken().getJwtToken()
}
});
}
});
}
//call refresh method in order to authenticate user and get new temp credentials
AWS.config.credentials.refresh((error) => {
if (error) {
console.error(error);
} else {
console.log('Successfully logged!');
}
});
note that you can not replace the login key with a variable because it will be interpreted literally. if you want to use a variable, the resolution to issue 17 has a working example
Use case 18. List all remembered devices for an authenticated user. In this case, we need to pass a limit on the number of devices retrieved at a time and a pagination token is returned to make subsequent calls. The pagination token can be subsequently passed. When making the first call, the pagination token should be null.
cognitoUser.listDevices(limit, paginationToken, {
onSuccess: function (result) {
console.log('call result: ' + result);
},
onFailure: function(err) {
alert(err);
}
});
Use case 19. List information about the current device.
cognitoUser.getDevice({
onSuccess: function (result) {
console.log('call result: ' + result);
},
onFailure: function(err) {
alert(err);
}
});
Use case 20. Remember a device.
cognitoUser.setDeviceStatusRemembered({
onSuccess: function (result) {
console.log('call result: ' + result);
},
onFailure: function(err) {
alert(err);
}
});
Use case 21. Do not remember a device.
cognitoUser.setDeviceStatusNotRemembered({
onSuccess: function (result) {
console.log('call result: ' + result);
},
onFailure: function(err) {
alert(err);
}
});
Use case 22. Forget the current device.
cognitoUser.forgetDevice({
onSuccess: function (result) {
console.log('call result: ' + result);
},
onFailure: function(err) {
alert(err);
}
});
Use case 23. Authenticate a user and set new password for a user that was created using AdminCreateUser API.
cognitoUser.authenticateUser(authenticationDetails, {
onSuccess: function (result) {
// User authentication was successful
},
onFailure: function(err) {
// User authentication was not successful
},
mfaRequired: function(codeDeliveryDetails) {
// MFA is required to complete user authentication.
// Get the code from user and call
cognitoUser.sendMFACode(mfaCode, this)
},
newPasswordRequired: function(userAttributes, requiredAttributes) {
// User was signed up by an admin and must provide new
// password and required attributes, if any, to complete
// authentication.
// the api doesn't accept this field back
delete userAttributes.email_verified;
// Get these details and call
cognitoUser.completeNewPasswordChallenge(newPassword, userAttributes, this);
}
});
Use case 24. Retrieve the MFA Options for the user in case MFA is optional.
cognitoUser.getMFAOptions(function(err, mfaOptions) {
if (err) {
alert(err);
return;
}
console.log('MFA options for user ' + mfaOptions);
});
Use case 25. Authenticating a user with a passwordless custom flow.
cognitoUser.setAuthenticationFlowType('CUSTOM_AUTH');
cognitoUser.initiateAuth(authenticationDetails, {
onSuccess: function(result) {
// User authentication was successful
},
onFailure: function(err) {
// User authentication was not successful
},
customChallenge: function(challengeParameters) {
// User authentication depends on challenge response
var challengeResponses = 'challenge-answer'
cognitoUser.sendCustomChallengeAnswer(challengeResponses, this);
}
});
Use case 26. Using cookies to store cognito tokens
To use the CookieStorage you have to pass it in the constructor map of CognitoUserPool and CognitoUser (when constructed directly):
var poolData = {
UserPoolId : '...', // Your user pool id here
ClientId : '...' // Your client id here
Storage: new AWSCognito.CognitoIdentityServiceProvider.CookieStorage({domain: ".yourdomain.com"})
};
var userPool = new AWSCognito.CognitoIdentityServiceProvider.CognitoUserPool(poolData);
var userData = {
Username: 'username',
Pool: userPool,
Storage: new AWSCognito.CognitoIdentityServiceProvider.CookieStorage({domain: ".yourdomain.com"})
};
The CookieStorage object receives a map (data) in its constructor that may have these values:
Use case 27. Selecting the MFA method and authenticating using TOTP.
var authenticationData = {
Username : 'username',
Password : 'password',
};
var authenticationDetails = new AWSCognito.CognitoIdentityServiceProvider.AuthenticationDetails(authenticationData);
var poolData = {
UserPoolId : '...', // Your user pool id here
ClientId : '...' // Your client id here
};
var userPool = new AWSCognito.CognitoIdentityServiceProvider.CognitoUserPool(poolData);
var userData = {
Username : 'username',
Pool : userPool
};
var cognitoUser = new AWSCognito.CognitoIdentityServiceProvider.CognitoUser(userData);
cognitoUser.authenticateUser(authenticationDetails, {
onSuccess: function (result) {
console.log('access token + ' + result.getAccessToken().getJwtToken());
},
onFailure: function(err) {
alert(err);
},
mfaSetup: function(challengeName, challengeParameters) {
cognitoUser.associateSoftwareToken(this);
},
associateSecretCode : function(secretCode) {
var challengeAnswer = prompt('Please input the TOTP code.' ,'');
cognitoUser.verifySoftwareToken(challengeAnswer, 'My TOTP device', this);
},
selectMFAType : function(challengeName, challengeParameters) {
var mfaType = prompt('Please select the MFA method.', '');
cognitoUser.sendMFASelectionAnswer(mfaType, this);
},
totpRequired : function(secretCode) {
var challengeAnswer = prompt('Please input the TOTP code.' ,'');
cognitoUser.sendMFACode(challengeAnswer, this, 'SOFTWARE_TOKEN_MFA');
},
mfaRequired: function(codeDeliveryDetails) {
var verificationCode = prompt('Please input verification code' ,'');
cognitoUser.sendMFACode(verificationCode, this);
}
});
Use case 28. Enabling and setting SMS MFA as the preferred MFA method for the user.
smsMfaSettings = {
PreferredMfa : true,
Enabled : true
};
cognitoUser.setUserMfaPreference(smsMfaSettings, null, function(err, result) {
if (err) {
alert(err);
}
console.log('call result ' + result)
});
Use case 29. Enabling and setting TOTP MFA as the preferred MFA method for the user.
totpMfaSettings = {
PreferredMfa : true,
Enabled : true
};
cognitoUser.setUserMfaPreference(null, totpMfaSettings, function(err, result) {
if (err) {
alert(err);
}
console.log('call result ' + result)
});
The Amazon Cognito Identity JavaScript SDK will make requests to the following endpoints
For most frameworks you can whitelist the domain by whitelisting all AWS endpoints with "*.amazonaws.com".
In order to authenticate with the Amazon Cognito Identity Service, the client needs to generate a random number as part of the SRP protocol. The AWS SDK is only compatible with modern browsers, and these include support for cryptographically strong random values. If you do need to support older browsers then you should be aware that this is less secure, and if possible include a strong polyfill for window.crypto.getRandomValues() before including this library.
v1.28.0:
v1.27.0:
v1.26.0:
v1.25.0:
v1.24.0:
v1.23.0:
v1.19.0:
v1.18.0:
v1.17.0:
v1.16.0:
v1.15.0:
v1.14.0:
v1.13.0:
v1.12.0:
v1.11.0:
v1.10.0:
v1.9.0:
v1.7.0:
v1.6.0:
v1.5.0:
v1.2.0:
v1.1.0:
v1.0.0:
GA release. In this GA service launch, the following new features have been added to Amazon Cognito Your User Pools.
Whats new
What has changed
v0.9.0:
FAQs
Amazon Cognito Identity Provider JavaScript SDK
The npm package amazon-cognito-identity-js receives a total of 324,153 weekly downloads. As such, amazon-cognito-identity-js popularity was classified as popular.
We found that amazon-cognito-identity-js demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 13 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.
Security News
Research
Socket's threat research team has detected five malicious npm packages targeting Roblox developers, deploying malware to steal credentials and personal data.