custom web experience with amazon q business

使用 Amazon Q Business 定制 Web 体验

⚡ 如果您在 2024 年 4 月 30 日或之后创建了新的 Amazon Q Business 应用程序，您现在可以使用下面提供的更新说明设置自定义 UI。

注意：本指南中提供的说明特定于 Cognito，但经过细微调整后，它们也应适用于其他符合 OIDC 2.0 的身份提供商 (IdP)。

客户通常希望能够将自定义功能集成到 Amazon Q 用户界面中，例如处理反馈、使用企业颜色和模板、自定义登录以及通过将用户界面集成到单个平台中来减少上下文切换。该代码存储库将展示如何使用 Amazon Cognito 进行用户身份验证并使用 Amazon Q SDK 在 Amazon Q 上集成自定义 UI，以通过 chat_sync API 以编程方式调用聊天机器人应用程序。

?‍ 工作流程包括以下步骤：

1. 首先，用户访问托管在应用程序负载均衡器后面的聊天机器人应用程序。

2. 系统会提示用户使用 Cognito 登录

3. UI 应用程序将来自 Cognito 的令牌与具有 Amazon Q 范围的 IAM Identity Center 令牌交换

4. UI 应用程序承担 IAM 角色并从安全令牌服务 (STS) 检索 AWS 会话，并使用 IAM 身份中心令牌进行增强以与 Amazon Q 交互

   • 以下博客文章解释了 IAM 身份中心和 Idp 之间令牌交换的详细流程

   ？博客1

   ？博客2

5. Amazon Q 使用 ChatSync API 进行对话。借助身份感知会话，Amazon Q 知道它正在与哪个用户交互。

   • 该请求使用以下强制参数。

     1. applicationId ：链接到 Amazon Q 对话的 Amazon Q 应用程序的标识符。

     2. userMessage ：对话中的最终用户消息。

   • Amazon Q 以 JSON 对象形式返回响应（Amazon Q 文档中详细介绍），下面是响应负载中的几个核心属性。

     1. systemMessage ：对话中人工智能生成的消息

     2. sourceAttributions ：用于生成对话响应的源文档。在 RAG（检索增强生成）中，这始终指的是企业知识库中的一个或多个文档，这些文档在 Amazon Q 中建立了索引。

部署此解决方案

先决条件：

在部署此解决方案之前，请确保已设置以下先决条件：

• 有效的 AWS 账户。
• 账户中的 AWS Identity and Access Management (IAM) 角色具有足够的权限来创建必要的资源。
  如果您拥有该帐户的管理员访问权限，则无需执行任何操作。
• 创建并导入到 AWS Certificate Manager (ACM) 中的 TLS 证书。
  更多详细信息，请参阅导入证书。
  如果您没有公共 TLS 证书，请按照下一部分中的步骤了解如何生成私有证书。
• 现有的、运行的 Amazon Q 应用程序
• IAM Identity Center，并通过配置电子邮件地址和名称在 Identity Center 中创建一些用户

生成私有证书

如果您已有 TLS 证书，则可以跳过此部分。
但是，如果您没有证书并希望继续运行此演示，则可以使用以下 openssl 命令生成与域关联的私有证书：

 openssl req 
  -x509 -nodes -days 365 -sha256 
  -subj '/C=US/ST=Oregon/L=Portland/CN=sampleexample.com' 
  -newkey rsa:2048 -keyout key.pem -out cert.pem

aws acm import-certificate --certificate fileb://cert.pem --private-key fileb://key.pem

➡️请注意，如果您在启动 AWS CloudFormation Stack 时未提供自定义 TLS 证书，则在访问 UI 时您将收到来自浏览器的警告。上面的说明向您展示了如何创建自签名证书，该证书可以用作备份，但对于生产用例当然不建议这样做。

您应该获取已由证书颁发机构验证的 TLS 证书，将其导入 AWS Certificate Manager，并在启动 AWS CloudFormation Stack 时引用它。

如果您希望继续使用自签名证书（用于开发目的），您应该能够跳过浏览器警告页面。使用 Chrome，您将看到“您的连接不是私有的”错误消息 (NET::ERR_CERT_AUTHORITY_INVALID)，但通过单击“高级”，您应该会看到一个继续的链接。

部署此解决方案：

步骤 1：启动以下 AWS CloudFormation 模板来部署 ELB、Cognito 用户池，包括用于托管 Web 应用程序的 EC2 实例。

为堆栈提供以下参数

•堆栈名称– CloudFormation 堆栈的名称（例如 AmazonQ-UI-Demo）

• AuthName – 分配给Amazon Cognito 用户池的全局唯一名称。请确保您的域名不包含任何保留字，例如 cognito、aws 或 amazon。

• CertificateARN – 上一步生成的CertificateARN

• IdcApplicationArn – Identity Center 客户应用程序 ARN，首次运行时将其保留为空，因为我们需要创建认知用户池作为该堆栈的一部分，以使用受信任的令牌颁发者创建 IAM Identity Center 应用程序

• PublicSubnetIds – 可用于部署EC2 实例和Application Load Balancer 的公有子网的ID。请选择至少 2 个公共子网

• QApplicationId – Amazon Q 的现有应用程序 ID

• VPCId – 可用于部署演示的现有 VPC 的 ID

？堆栈完成后，从“输出”选项卡复制以下键。

受众：在 Identity Center 中设置客户应用程序的受众

RoleArn ：在 Identity Center 中设置令牌交换所需的 IAM 角色的 ARN

TrustedIssuerUrl ：用于设置身份中心的受信任颁发者的端点

URL ：用于访问 Streamlit 应用程序的负载均衡器 URL

步骤 2：创建 IAM 身份中心应用程序

• 导航到 AWS IAM Identity Center，然后添加新的自定义托管应用程序。

  选择应用程序类型->然后选择OAuth2.0->下一步

  

  如果您找不到创建新的自定义托管应用程序的选项，请使用 IAM Identity Center 启用组织。

• 提供应用程序名称和描述，然后选择以下选项，如图所示

  

• 现在创建一个可信的令牌发行者

  

• 在颁发者 URL -> 提供步骤 1 中的TrustedIssuerUrl中，提供颁发者名称并将映射属性保留为电子邮件

  

• 然后导航回 IAM Identity Center 应用程序身份验证设置 ，选择在上一步中创建的可信令牌颁发者[如果在列表中没有看到，请刷新]并添加 Aud 声明 -> 提供步骤 1 中的受众，然后单击下一个

  

• 在指定应用程序凭证中，输入 IAM 角色 -> 提供步骤 1 中的RoleArn

  

• 然后查看所有步骤并创建应用程序。

• 创建应用程序后，转到应用程序 -> 分配的用户和组。

  

• 然后设置用于身份传播的可信应用程序，按照以下步骤将 Amazon Q 作为用于身份传播的可信应用程序

  

步骤 4：创建 IAM Identity Center 应用程序后，复制应用程序 ARN 并导航到 Cloudformation 以更新之前创建的堆栈。在参数IdcApplicationArn中输入 Identity Center 应用程序 ARN 并运行堆栈。

步骤 5：更新完成后，导航到 Cloudformation 输出选项卡以复制 URL 并在浏览器中打开 URL

步骤 6：Streamlit 应用程序将提示连接 Cognito ，对于首次登录尝试注册，请使用 IAM Identity Center 中已存在的用户的相同电子邮件 ID 和密码。

⚡ 为了消除在 Cognito 用户池和身份中心中配置用户的需要，您可以按照下面的链接在身份中心中创建第二个自定义应用程序 (SAML)。此自定义应用程序将充当 Cognito 用户池的身份提供商。

？视频

？指示

通过 AWS Session Manager 连接到 EC2[可选]：

 sudo -i
cd /opt/custom-web-experience-with-amazon-q-business

故障排除

有关详细信息，请参阅故障排除。

安全

请参阅贡献以获取更多信息。

执照

该库根据 MIT-0 许可证获得许可。请参阅许可证文件。