Amazon Cognito
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 Amazon AWS 入门

教程:为 JavaScript 应用程序集成用户池

本教程将帮助您通过适用于 JavaScript 的 Amazon Cognito 开发工具包开始使用用户池。

步骤 1:使用控制台为 JavaScript 应用程序创建用户池

以下过程介绍如何创建用户池以及如何在应用程序中使用用户池。此过程将创建一个用户池 ID 和应用程序客户端 ID。有关自定义这些设置的信息,请参阅用户池参考 (AWS 管理控制台)

为应用程序创建用户池的步骤

  1. 登录 Amazon Cognito 控制台

  2. 选择 Manage your User Pools

  3. 选择 Create a User Pool

  4. Pool name 中,键入池的名称,然后选择 Review defaults。这样将使用默认设置创建池。

  5. 在左侧导航窗格中,选择 Attributes 以指定哪些属性为必需属性以及哪些属性要用作别名。设置以下属性之后,池中的用户需要先验证其电子邮件地址,然后才可以使用用户名或电子邮件地址登录。

    1. 对于 email,选择 RequiredAlias

    2. 对于 phone number,选择 RequiredAlias

    3. 对于 given name,选择 Required

    4. 选择 Save changes

  6. 在左侧导航窗格中,选择 Policies 以指定密码策略。在本教程中,请使用默认设置。

  7. 在左侧导航窗格中选择 Verifications。在此页面上,您可以自定义发送给池中的用户,用于提供验证代码的消息。在本教程中,请使用默认设置。

  8. 在左侧导航窗格中,选择 Apps,然后选择 Add an app。您可以为一个用户池创建多个应用程序客户端,还可以为每个平台创建一个应用程序。

  9. 对于 App name,键入应用程序的名称。确保清除了 Generate client secret 复选框,然后选择 Set attribute read and write permissions。选择需要写入权限的属性。必需属性始终具有写入权限。

    注意

    Amazon Cognito JavaScript 开发工具包不使用该应用程序客户端密钥。如果您使用应用程序客户端密钥配置用户池应用程序客户端,开发工具包会引发异常。

  10. 选择 Create app,然后选择 Save changes

  11. 在左侧导航栏中,选择 Review,然后选择 Create pool

  12. 请记下池 ID 和客户端 ID。您可以在左侧导航栏的 Apps 下找到该应用程序客户端 ID。

步骤 2:在应用程序中创建一个用户池对象

要创建用户池对象,您需要用到在步骤 1 中获取的用户池 ID 和客户端 ID。以下示例显示了如何创建一个 CognitoUserPool 对象。JavaScript 开发工具包不支持应用程序客户端密钥。如果您使用应用程序客户端密钥配置用户池应用程序客户端,开发工具包会引发异常。

var poolData = { UserPoolId : '...', // your user pool id here ClientId : '...' // your app client id here }; var userPool = new AmazonCognitoIdentity.CognitoUserPool(poolData); var userData = { Username : '...', // your username here Pool : userPool };

步骤 3:为应用程序注册用户

在创建用户池对象后,用户可以注册该应用程序。用户的信息可以通过 Web UI 收集,并用于填充 signUp 调用中所传递的 CognitoUserAttribute 对象。

var attributeList = []; var dataEmail = { Name : 'email', Value : '...' // your email here }; var dataPhoneNumber = { Name : 'phone_number', Value : '...' // your phone number here with +country code and no delimiters in front }; var attributeEmail = new AmazonCognitoIdentity.CognitoUserAttribute(dataEmail); var attributePhoneNumber = new AmazonCognitoIdentity.CognitoUserAttribute(dataPhoneNumber); attributeList.push(attributeEmail); attributeList.push(attributePhoneNumber); var cognitoUser; userPool.signUp('username', 'password', attributeList, null, function(err, result){ if (err) { alert(err); return; } cognitoUser = result.user; console.log('user name is ' + cognitoUser.getUsername()); });

步骤 4:为应用程序确认用户

注册后,用户输入通过 SMS 或电子邮件发送的代码 (取决于用户池设置),以确认注册。或者,您也可以使用 PreSignUp AWS Lambda 函数自动确认用户。要确认注册,您必须收集用户收到的代码 (在以下示例中为“123456”) 并使用它,如下所示。

cognitoUser.confirmRegistration('123456', true, function(err, result) { if (err) { alert(err); return; } console.log('call result: ' + result); });

注册代码可以使用 cognitoUser 对象的 resendConfirmationCode 方法重新发送。这是一个未经身份验证的调用,只需要用户名、客户端 ID 和用户池信息。

步骤 5:让用户登录应用程序

已确认的用户登录以获取会话。该会话包含以下内容:一个包含用户声明的 ID 令牌;一个访问令牌,在内部用于执行经过身份验证的调用;一个刷新令牌,在内部使用,用于在会话过期后按每小时一次的频率刷新会话。有关令牌的更多信息,请参阅将令牌与用户池结合使用。如果登录成功,则调用 onSuccess 回调。如果登录失败,则调用 onFailure 回调。如果登录需要 MFA,则调用 mfaRequired 回调,并且您必须在 cognitoUser 对象上调用 sendMFACode。必须传递收到的验证代码,然后用户才能登录。

var authenticationData = { Username : '...', // your username here Password : '...', // your password here }; var authenticationDetails = new AmazonCognitoIdentity.AuthenticationDetails(authenticationData); var cognitoUser = new AmazonCognitoIdentity.CognitoUser(userData); cognitoUser.authenticateUser(authenticationDetails, { onSuccess: function (result) { var accessToken = result.getAccessToken().getJwtToken()); }, onFailure: function(err) { alert(err); }, mfaRequired: function(codeDeliveryDetails) { var verificationCode = prompt('Please input verification code' ,''); cognitoUser.sendMFACode(verificationCode, this); } });

步骤 6:获取用户详细信息

登录后,用户可以执行授权操作,例如检索用户属性,验证用户属性 (如未经验证的电子邮件地址),删除用户属性,更新用户属性,更改用户密码以及删除用户账户。对于将 MFA 设置为可选的用户池,用户可以为自己启用或禁用 MFA。从应用程序注销会清除本地用户会话,用户必须再次登录才能建立新的会话。

如果用户忘记密码,他们可以启动忘记密码流程。系统会将代码发送给用户。用户可以使用此代码和新密码完成流程。相关调用是未经身份验证的 cognitoUser 对象上的 forgotPassword;相关回调如以下示例所示。

cognitoUser.forgotPassword({ onSuccess: function (result) { console.log('call result: ' + result); }, onFailure: function(err) { alert(err); }, inputVerificationCode() { var verificationCode = prompt('Please input verification code ' ,''); var newPassword = prompt('Enter new password ' ,''); cognitoUser.confirmPassword(verificationCode, newPassword, this); } });

步骤 7:为应用程序用户获取访问 AWS 资源的凭证

如果您希望使用其他 AWS 服务,您必须先创建一个 Amazon Cognito 身份池。创建此身份池后,您可以通过传递之前获取的身份池 ID 和 ID 令牌在用户登录时获取 AWS 凭证。以下示例展示了如何通过 Logins 映射填充 IdentityPoolId 并传递 ID 令牌。

AWS.config.credentials = new AWS.CognitoIdentityCredentials({ IdentityPoolId: 'us-east-1:XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX', Logins: { 'cognito-idp.us-east-1.amazonaws.com/us-east-1_XXXXXXXXX': result.getIdToken().getJwtToken() } }); AWS.config.credentials.get(function(err){ if (err) { alert(err); } });

后续步骤

有关更多示例以及本教程中所用代码的概述,请参阅 Amazon Cognito 身份 JavaScript GitHub 存储库