将自定义属性发送至 Amazon Cognito 并将其注入令牌中

Carlos Alessandro Ribeiro 和 Mauricio Mendoza，Amazon Web Services

Summary

通过向 Amazon Cognito 身份验证流程发送自定义属性，可为应用程序提供额外上下文信息，实现更精细的访问控制，并更轻松地管理用户配置文件和身份验证要求。这些功能适用于各类应用程序及场景，有助于提升应用程序的整体安全性与功能性。

此模式显示当应用程序需要为访问令牌或身份（ID）令牌提供额外上下文时，如何向 Amazon Cognito 身份验证流程发送自定义属性。您使用 Node.js 作为后端应用程序。该应用程序会对 Amazon Cognito 用户池中的用户进行身份验证，并传递生成令牌所需的自定义属性。您可以使用 Amazon Cognito 的 AWS Lambda 触发器来自定义身份验证流程，而无需进行大量的代码自定义或完成大量工作。

先决条件和限制

先决条件

限制

架构

目标架构

下图显示了此模式的目标架构。它还显示了 Node.js 应用程序如何与后端协同实现数据库更新。但是，后端数据库更新不在此模式的范围之内。

下图显示了如下工作流：

自动化和扩展

您可以使用AWS CloudFormation、、HashiCorp Terraform 或任何支持的基础设施即代码 (IaC) 工具，自动配置 Amazon Cognito 用户池、 AWS Lambda 函数、数据库实例和其他资源。AWS Cloud Development Kit (AWS CDK)如需扩展部署规模，请使用持续集成和持续交付（CI/CD）管道，这有助于避免手动部署可能引发的错误。

工具

AWS 服务

其他工具

最佳实践

建议您实施以下最佳实践：

如需了解其他最佳实践，请参阅 Amazon Cognito 文档中的 Amazon Cognito 用户池的安全最佳实践。

操作说明

aws cognito-idp sign-up \
   --client-id <ClientID> \
   --username <jane@example.com> \
   --password <PASSWORD> \
   --user-attributes Name="email",Value="<jane@example.com>" Name="name",Value="<Jane>"

export USERNAME="<COGNITO_USER_NAME>"
export PASSWORD="<COGNITO_USER_PASSWORD>"
export USER_POOL_ID="<COGNITO_USER_ID>"
export CLIENT_ID="<COGNITO_CLIENT_ID>"

npm run build
npm start

问题排查

相关资源

附加信息

示例 TypeScript 文件

以下代码示例是一个通过使用 AWS 软件开发工具包向 Amazon Cognito 发送自定义属性来调用身份验证过程的 TypeScript 文件：

import * as AmazonCognitoIdentity from "amazon-cognito-identity-js";

const userPoolId: string = process.env.USER_POOL_ID ?? '';
const clientId: string = process.env.CLIENT_ID ?? '';

const poolData = {
  UserPoolId: userPoolId,
  ClientId: clientId
};
const userPool = new AmazonCognitoIdentity.CognitoUserPool(poolData);

export const loginWithCognitoSDK = function (userName: string, password: string) {
  const authenticationDetails = new AmazonCognitoIdentity.AuthenticationDetails({
    Username: userName,
    Password: password,
    ClientMetadata: {
        customGroup: "MyCustomGroup",
        customApplicationData: "Custom data from a custom application"
    }
  });
  const userData = {
    Username: userName,
    Pool: userPool
  };

  const cognitoUser = new AmazonCognitoIdentity.CognitoUser(userData);

  // Authenticate the user using the authenticationDetails object
  cognitoUser.authenticateUser(authenticationDetails, {
    onSuccess: function (result: any) {},
    onFailure: function (err: any) {},
  });
}
loginWithCognitoSDK(process.env.USERNAME ?? '', process.env.PASSWORD ?? '');

该示例使用的 SDK 中的AuthenticationDetails模型 JavaScript 来提供用户名、密码和ClientMetadada。在 Amazon Cognito 中进行身份验证后，可以从访问令牌和 ID 令牌中检索客户端元数据。

示例 Lambda 函数

以下代码示例是一个 Lambda 函数，该已与 Amazon Cognito 的令牌生成前触发器关联。它可以帮助您自定义 Amazon Cognito 使用的访问令牌和 ID 令牌。这些令牌会通过您架构之间的集成传递。此示例包含名为 customApplicationData 的自定义声明属性以及名为 MyCustomGroup 的自定义组名称：

export const handler = async(event, context, callback) => {
    event.response = {
        claimsOverrideDetails: {
            claimsToAddOrOverride: { customApplicationData: event.request.clientMetadata.customApplicationData },
            groupOverrideDetails: { groupsToOverride: [event.request.clientMetadata.customGroup] }
        }
    };
    callback(null, event);
};

示例访问令牌

您可以对访问令牌进行解码，以查看已添加的自定义属性。以下是示例访问令牌：

{
  "sub": "6daf331f-4451-48b4-abde-774579299204",
  "cognito:groups": [
    "MyCustomGroup"
  ],
  "iss": "https://cognito-idp.<REGION>.amazonaws.com/<USERPOOL_ID>",
  "client_id": "<YOUR_CLIENT_ID>",
  "origin_jti": "acff7e91-09f9-4fde-8eec-38b0f8c47cdc",
  "event_id": "c5113a9c-1f01-435b-9b73-a5cd3e88514e",
  "token_use": "access",
  "scope": "aws.cognito.signin.user.admin",
  "auth_time": 1677979246,
  "exp": 1677982846,
  "iat": 1677979246,
  "jti": "5c9c2708-a871-4428-bd9b-18ad261bea90",
  "username": "<USER_NAME>"
}

示例 ID 令牌

您可以对访问令牌进行解码，以查看已添加的自定义属性。以下是示例访问令牌：

{
  "sub": "6daf331f-4451-48b4-abde-774579299204",
  "cognito:groups": [
    "MyCustomGroup"
  ],
  "iss": "https://cognito-idp.<REGION>.amazonaws.com/<USERPOOL_ID>",
  "cognito:username": "<USER_NAME>",
  "origin_jti": "acff7e91-09f9-4fde-8eec-38b0f8c47cdc",
  "customApplicationData": "Custom data from a custom application",
  "aud": "<YOUR_CLIENT_ID>",
  "event_id": "c5113a9c-1f01-435b-9b73-a5cd3e88514e",
  "token_use": "id",
  "auth_time": 1677979246,
  "exp": 1677982846,
  "iat": 1677979246,
  "jti": "f7ca006b-f25b-44d2-a7a4-6e6423f4201f",
  "email": "<USER_EMAIL>"
}