使用 Amazon Cognito 和 iaC 自动化将 Amazon Quick Sight 视觉组件嵌入到网络应用程序中 - AWS 规范指引
Summary先决条件和限制架构工具最佳实践操作说明问题排查相关资源

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

使用 Amazon Cognito 和 iaC 自动化将 Amazon Quick Sight 视觉组件嵌入到网络应用程序中

Ishita Gupta 和 Srishti Wadhwa，Amazon Web Services

Summary

这种模式提供了一种专门的方法，通过使用注册用户嵌入和简化的 Amazon Cognito 身份验证，将 Amazon Quick Sight 视觉组件嵌入到 React 应用程序中。然后通过基础设施即代码 (IaC) 模板部署这些资源。与传统的仪表板嵌入不同，该解决方案隔离了特定的图表和图形，以便直接集成到React应用程序中，从而极大地提高了性能和用户体验。

该架构在 Amazon Cognito 用户管理和 Quick Sight 权限之间建立了高效的身份验证流程：用户通过 Amazon Cognito 进行身份验证，并根据 Quick Sight 中的控制面板共享规则访问其授权的可视化效果。这种简化的方法无需直接访问 Quick Sight 控制台，同时还能保持强大的安全控制。

整个环境通过单一模板进行部署，该 AWS CloudFormation 模板配置了所有必要的基础架构组件，包括：

  • 使用 AWS Lambda 和 Amazon API Gateway 的无服务器后端

  • 通过亚马逊 CloudFront、亚马逊简单存储服务 (Amazon S3) Semple Service 和 AWS WAF

  • 使用 Amazon Cognito 进行身份管理

所有组件均按照安全最佳实践进行配置，包括最低权限 AWS Identity and Access Management (IAM) 策略、 AWS WAF 保护和 end-to-end加密。

该解决方案非常适合希望将安全的交互式分析集成到其应用程序中，同时保持对用户访问权限的精细控制的开发团队和组织。该解决方案使用 AWS 托管服务和自动化来简化嵌入流程、增强安全性并确保可扩展性，以满足不断变化的业务需求。

目标受众和用例：

  • 想要将分析嵌入到 React 应用程序中的@@ 前端开发者

  • 想要提供按用户或基于角色的数据可@@ 视化的软件即服务 (SaaS) 产品团队

  • 有兴趣将 AWS 分析集成到自定义门户中的@@ 解决方案架构师

  • 商业智能 (BI) 开发人员，他们希望向经过身份验证的用户展示视觉效果而无需完全访问控制面板

  • 想要在内部工具中嵌入交互式 Quick Sight 图表的@@ 企业团队

先决条件和限制

先决条件

要成功实现此模式，请确保以下内容准备就绪：

  • A@@ ctiv e AWS 账户 AWS 账户 — 有权部署 CloudFormation 堆栈和创建 Lambda、API Gateway、Amazon Cognito CloudFront 和 Amazon S3 资源。

  • Amazon Quick Sight 账户 — 一个活跃的 Quick Sight 账户，其中至少有一个包含视觉效果的控制面板。有关设置说明，请参阅教程：使用 Amazon Quick Suite 文档中的示例数据创建 Amazon Quick Sight 控制面板。

  • 包含以下@@ 内容的开发环境：

    • Node.js（版本 16 或更高版本）

    • 安装了 npm 或纱线

    • Vite 作为 React 构建工具

    • React（版本 19.1.1）

  • 仪表板共享 — 仪表板必须在 Quick Sight 中共享，并且实现者必须登录才能访问嵌入式视觉对象或仪表板。

限制

  • 此模式使用注册用户嵌入方法，该方法要求实现者拥有有效的 Quick Sight 帐户。

  • 仅限于与实现此模式的经过身份验证的 Quick Sight 用户明确共享的仪表板和视觉对象。如果实现者没有正确的访问权限，则嵌入网址生成将失败，视觉效果将无法加载。

  • CloudFormation 堆栈必须部署在支持 Quick Sight、API Gateway 和 Amazon Cognito AWS 区域 的地方。有关区域可用性，请参阅按区域划分的AWS 服务。

产品版本

架构

目标架构

下图显示了此模式的架构和工作流。

将 Quick Sight 视觉效果嵌入 React 应用程序的架构和工作流程。

在此工作流程中：

  1. 用户访问应用程序。用户使用浏览器打开 React Web 应用程序。请求被路由到 CloudFront 分发，该分发充当应用程序的内容交付网络。

  2. AWS WAF 过滤恶意请求。 在请求到达之前 CloudFront，它就会通过 AWS WAF。 AWS WAF 根据安全规则检查流量并阻止任何恶意或可疑的请求。

  3. 亚马逊 S3 提供静态文件。如果请求是干净的，则使用原始访问控制 (OAC) 从私有 S3 存储桶中 CloudFront 检索静态前端资产（HTML、JS、CSS），然后将其交付给浏览器。

  4. 用户登录。应用程序加载完毕后，用户通过 Amazon Cognito 登录，Amazon Cognito 会对用户进行身份验证并返回安全 JSON 网络令牌 (JWT)，用于授权的 API 访问。

  5. 应用程序发出 API 请求。登录后，React 应用程序对 API Gateway 上的/get-embed-url端点进行安全调用，并在请求标头中传递 JWT 令牌进行身份验证。

  6. 令牌已通过验证。API Gateway 使用亚马逊 Cognito 授权机构验证令牌。如果令牌有效，则请求继续执行；否则，请求会被拒绝，并返回 401（未授权）响应。

  7. 该请求被定向到 Lambda 进行处理。然后，经过验证的请求会被转发到后端 Lambda 函数。此函数负责为请求的 Quick Sight 视觉效果生成嵌入网址。

  8. Lambda 从 Quick Sight 生成嵌入网址。IAM 使用具有适当权限的 IAM 角色调用 Quick Sight GenerateEmbedUrlForRegisteredUser API 来生成安全的、用户范围的可视化网址。

  9. Lambda 将嵌入网址返回到 API Gateway。作为 JSON 响应的一部分，Lambda 将生成的嵌入网址发送回 API Gateway。然后准备好将该响应传送到前端。

  10. 嵌入的 URL 将发送到浏览器。嵌入网址作为 API 响应返回给浏览器。

  11. 视觉效果将显示给用户。 React 应用程序接收响应并使用 Quick Sight Embedding SDK 向用户呈现特定的视觉效果。

自动化和扩展

后端和前端部署完全自动化 CloudFormation，使用在单个部署中预置所有必需的 AWS 资源，包括 Amazon Cognito、Lambda、API Gateway、A CloudFront mazon S3 AWS WAF、、、、IAM 角色和 CloudWatch 亚马逊。

这种自动化可确保在所有环境中实现一致且可重复的基础架构。所有组件都会自动扩展：Lambda 会根据函数调用进行调整，在全球范围内 CloudFront 提供缓存内容，API Gateway 可根据传入的请求进行扩展。

工具

AWS 服务

  • Amazon Quick Sight 是一项云原生商业智能服务，可帮助您创建、管理和嵌入交互式仪表板和视觉对象。

  • Amazon API Gateway 管理着它 APIs 充当 React 应用程序和后端服务之间的桥梁。

  • AWS Lambda是一种无服务器计算服务，这种模式使用它来生成安全的 Quick Sight URLs 动态嵌入，并根据请求自动扩展。

  • Amazon Cognito 为用户提供身份验证和授权，并为 API 访问颁发安全令牌。

  • Amazon S3 托管这种模式的静态前端资产，并通过 CloudFront安全的方式为它们提供服务。

  • Amazon 以低延迟在全球范围内 CloudFront 提供前端内容，并与之集成 AWS WAF 以进行流量过滤。

  • AWS WAF通过应用安全规则和速率限制来保护 Web 应用程序免受恶意流量的侵害。

  • AWS CloudFormation可在单个部署中自动配置和配置所有应用程序资源。

  • 亚马逊从 Lambda、API Gateway CloudWatch 收集日志和指标， AWS WAF 用于监控和故障排除。

开发工具

  • React JS 是一个前端框架，这种模式使用它来构建 Web 应用程序和集成嵌入式 Quick Sight 视觉效果。

  • Vite 是一种构建工具，用于快速开发和优化 React 应用程序的生产构建。

  • Qu@@ ick Sight Embedding SDK 有助于将 Quick Sight 视觉效果嵌入 React 应用程序，并实现应用程序和视觉效果之间的无缝交互。

代码存储库

此模式的代码可在 React 存储库中的 GitHub Amazon Quick Sight Visual Embedding 中找到。

最佳实践

此模式会自动实现以下安全最佳实践：

  • 使用 Amazon Cognito 用户池进行基于 JWT 的身份验证，以及可选的多因素身份验证 (MFA)。

  • APIs 使用 Amazon Cognito 授权机构进行保护，并在所有服务中强制执行最低权限 IAM 政策。

  • 实现 Quick Sight 注册用户嵌入，并自动为用户配置读者角色。

  • 通过 CloudFront 和 HTTPS 强制执行支持 TLS 1.2 及更高版本的传输中加密。

  • 使用带版本控制和 OAC 的 Amazon S3 的 AES-256 对静态数据进行加密。

  • 使用限制和配额配置 API Gateway 使用计划。

  • 使用预留并发性和环境变量保护来保护 Lambda。

  • 启用 Amazon S3 CloudFront、Lambda 和 API Gateway 的日志记录；使用监控服务。 CloudWatch

  • 加密日志、应用访问控制，并对非 HTTPS 或未加密的上传强制执行拒绝策略。

此外，我们建议采取以下措施：

  • CloudFormation 用于自动化部署并在不同环境中保持一致的配置。

  • 确保每个用户都具有访问嵌入式视觉效果的正确的 Quick Sight 权限。

  • 使用 Amazon Cognito 授权者保护 API Gateway 终端节点，并对所有 IAM 角色强制执行最低权限原则。

  • 将诸如 Amazon 资源名称 (ARNs) 和环境变量之类的敏感信息存储 IDs 在环境变量中，而不是对其进行硬编码。

  • 通过减少依赖关系和提高冷启动性能来优化 Lambda 函数。有关更多信息，请参阅 AWS 博客文章 “优化 AWS Lambda 使用高级启动策略的冷启动性能”。 SnapStart

  • 将您的 CloudFront 域名添加到 Quick Sight 许可名单，以启用安全的视觉嵌入。

  • 使用和进行日志、警 AWS WAF 报 CloudWatch 和流量保护来监控性能和安全性。

其他推荐的最佳做法

  • 使用带有 SSL 证书的自定义域名， AWS Certificate Manager 以提供安全和品牌化的用户体验。

  • 使用客户托管 AWS Key Management Service (AWS KMS) 密钥加密 Amazon S3 数据和 CloudWatch 日志，以便更好地控制加密。

  • 使用地理封锁、SQL 注入 (SQLi)、跨站脚本 (XSS) 保护和自定义过滤器来扩展 AWS WAF 规则，以增强威胁防御。

  • 启用 CloudWatch 警报 AWS Config、和， AWS CloudTrail 以实现实时监控、审计和配置合规性。

  • 应用精细的 IAM 策略，强制执行 API 密钥轮换，并仅在绝对必要时才允许跨账户访问。

  • 定期进行安全评估，确保与合规框架保持一致，例如系统和组织控制2 (SOC 2)、《通用数据保护条例》(GDPR) 和《健康保险流通与责任法案》(HIPAA)。

操作说明

Task说明所需技能

克隆存储库。

将此解决方案的 GitHub 存储库克隆到您的本地系统并导航到项目目录：

git clone https://github.com/aws-samples/sample-quicksight-visual-embedding.git

cd sample-quicksight-visual-embedding

该存储库包含部署解决方案所需的 CloudFormation 模板和 React 源代码。

应用程序开发人员
Task说明所需技能

部署 模板。

  1. 登录 AWS 管理控制台 并打开AWS CloudFormation 控制台。

  2. 在堆栈页面上，选择右上角的创建堆栈，然后选择使用新资源（标准）。

  3. 在 “创建堆栈” 页面上，在 “先决条件-准备模板” 中，选择 “选择现有模板”。

  4. 对于指定模板，选择上传模板文件。

  5. 从本地 GitHub 存储库上传template.yaml文件，然后选择 “下一步”。

  6. 在指定堆栈详细信息页面上，输入堆栈名称（例如quicksight-embedding-stack）。

  7. 在配置堆栈选项页面上，保留默认设置，然后选中复选框以确认 IAM 资源的创建。选择下一步。

  8. 在审查并创建页面上，选择提交。

 有关更多信息，请参阅 CloudFormation 文档中的创建和管理堆栈。

AWS 管理员

监控堆栈创建。

在 “事件” 选项卡中监控堆栈，直到其状态为 CREATE_ COMPLETE。

AWS 管理员

检索堆栈输出。

  1. 部署完成后，选择 “输出” 选项卡。

  2. 注意关键输出：ApiGatewayUrlUserPoolId、UserPoolClientId、CloudFrontDomainName、和S3BucketName。您将在后续步骤中使用此信息。

AWS 管理员
Task说明所需技能

检索快速视觉标识符。

  1. 打开 Quick Sight 仪表板。

  2. 记下计划嵌入到 Web 应用程序中的每个视觉对象的仪表板 ID、工作表 ID 和视觉 ID。

快速瞄准管理员

配置你的本地 React 环境。

要设置本地 React 环境并将其链接到 AWS 资源，请在本地 GitHub 存储库的my-app/文件夹中创建一个.env文件。在文件中填充以下内容：

  • 你的 AWS 区域

  • Amazon Cognito 池信息（来自 CloudFormation 堆栈输出）

  • API Gateway 端点（来自 CloudFormation 堆栈输出）

  • Quick Sight 视觉 IDs (DashboardIdSheetId、、VisualId)

以下是一个示例.env文件：

VITE_AWS_REGION=us-east-1

# Cognito Configuration (from CloudFormation outputs)
VITE_USER_POOL_ID=us-east-1_xxxxxxxxx VITE_USER_POOL_WEB_CLIENT_ID=xxxxxxxxxxxxxxxxxxxxxxxxxx

# API Configuration (from CloudFormation outputs)
VITE_API_URL=https:/your-api-id.execute-api.us-east-1.amazonaws.com/prod

# QuickSight Visual Configuration
VITE_DASHBOARD_ID=your-dashboard-id 
VITE_SHEET_ID=your-sheet-id 
VITE_VISUAL_ID=your-visual-id
应用程序开发人员
Task说明所需技能

在 Cognito 中创建或管理用户

要允许经过身份验证的用户访问嵌入式 Quick Sight 视觉对象，您需要先在 Amazon Cognito 中创建用户：

  1. 在 Amazon Cognito 控制台上，选择用户池，然后选择匹配的池UserPoolId（从 CloudFormation 输出中）。

  2. 向池中添加用户。可从两个选项中选择：

AWS 管理员

提供快速查看仪表板访问权限

要提供对 Quick Sight 视觉效果的访问权限，请向经过身份验证的用户提供查看者权限访问权限：

  1. 在 Quick Sight 控制台上，选择仪表板。

  2. 通过选择要共享的仪表板名称来选择该仪表板。

  3. 在仪表板页面的右上角，选择共享。

  4. 在共享面板中，选择与特定用户共享。

  5. 要添加新用户，请选择邀请用户或加号 (+) 图标。

  6. 在电子邮件字段中，输入收件人的完整电子邮件地址。（此电子邮件必须与用户的 Amazon Cognito 登录信息完全匹配）

  7. 从电子邮件字段旁边的 “权限” 菜单中，选择 “查看者”。

  8. 要发送邀请并授予访问权限，请选择共享。

每位用户都将收到一封包含仪表板链接的电子邮件。您可以随时通过 “共享” 菜单修改权限。

有关更多信息，请参阅 Amazon Quick Suite 文档中的授予个人 Amazon Quick Sight 用户和群组访问 Amazon Quick Sight 中控制面板的权限。

快速瞄准管理员
Task说明所需技能

安装依赖关系并生成项目。

在 React 应用程序目录中，运行以下命令以生成经过优化的生产文件：

cd my-app
npm install
npm run build
应用程序开发人员

将构建文件上传到 Amazon S3。

将my-app/dist/目录中的所有文件上传到由配置的 S3 存储桶 CloudFormation （不要上传文件夹本身）。

应用程序开发人员

创建 CloudFront 失效。

在CloudFront 控制台上，为部署后刷新缓存内容/*的路径创建失效。有关说明，请参阅 CloudFront 文档中的使文件失效。

AWS 管理员
Task说明所需技能

将该 CloudFront 域名添加到 Quick Sight 许可名单。

要使您的 CloudFront 域能够安全地嵌入 Quick Sight 视觉效果，请执行以下操作：

  1. 在 Quick Sight 控制台上，选择管理 Quick Sight、域名和嵌入。

  2. 将 CloudFront 域添加到 “域” 框中（例如，https://d1234567890abc.cloudfront.net）。

  3. 选择添加域。

快速瞄准管理员
Task说明所需技能

打开 React 应用程序。

使用CloudFront 域（来自 CloudFormation 输出）在浏览器中打开已部署的 React Web 应用程序。

应用程序所有者

验证身份验证。

使用 Amazon Cognito 凭证登录应用程序，通过 API Gateway 验证身份验证流程和 JWT 验证。

应用程序所有者

验证嵌入式视觉效果。

确认 Quick Sight 视觉效果是否基于用户特定的访问权限在应用程序中正确加载。

应用程序所有者

验证 API 和 Lambda 的连接。

确认应用程序可以成功调用 /get-embed-url API 并检索有效的 Quick Sight 嵌入内容 URLs 而不会出现错误。

应用程序所有者
Task说明所需技能

使用监控 CloudWatch。

您可以使用可 AWS 观察性工具来监控应用程序，并在生产环境中保持安全、可扩展的性能。

查看 Lambda 日志、API Gateway 指标和 Amazon Cognito 身份验证事件 CloudWatch ，以确保应用程序运行状况并检测异常情况。

AWS 管理员

跟踪 AWS WAF 和 CloudFront 记录。

检查 AWS WAF 日志中是否有被阻止或可疑的请求，并检查 CloudFront 访问日志以了解性能和缓存指标。

AWS 管理员

问题排查

问题解决方案

“域名不允许” 错误

  1. 在 Quick Sight 控制台上，选择管理 Quick Sight、域名和嵌入。

  2. 添加您的 CloudFront 域名（例如，https://d1234567890abc.cloudfront.net）。

  3. 保存配置并重新加载应用程序。

身份验证错误

可能的原因：

  • 文件中的 Amazon Cognito 用户池 ID 或应用程序客户端 ID 不正确。.env

  • 未在 Amazon Cognito 用户池中确认用户。

  • API 请求中的 JWT 令牌无效或缺失。

解决方案：

  • 验证文件中的 Amazon Cognito 配置值。.env

  • 在 Amazon Cognito 控制台上，选中 “用户” 选项卡以验证用户是否处于活动状态。

  • 确认授权标头包含有效的 JWT 令牌。

  • 在 API Gateway 控制台上，选中授权者以验证 API Gateway 是否正在使用 Amazon Cognito 授权方进行身份验证。

API Gateway 错误

可能的原因：

  • API Gateway 中缺少或配置错误 Amazon Cognito 授权方。

  • Lambda 权限不足，无法调用 Quick Sight API。

  • .env和 CloudFormation 输出之间的 API 网址不匹配。

解决方案：

  • 再次确认 API Gateway 调用网址在您的.env文件中。

  • 在 API Gateway 控制台上，选中授权者以验证 Amazon Cognito 设置。

  • 将所需的 IAM 策略与附加quicksight:GenerateEmbedUrlForRegisteredUser到 Lambda 执行角色。

  • 查看 CloudWatch 日志，了解详细的 API 或权限错误。有关更多信息，请参阅 API Gateway 文档。

Quick Sight 视觉效果无法加载

可能的原因：

  • 环境配置中的 Quick Sight 仪表板 ID、工作表 ID 或视觉 ID 不正确。

  • Quick Sight 用户无法访问视觉对象或仪表板。

  • API Gateway 中缺少跨域资源共享 (CORS) 配置。

解决方案：

  • IDs 从仪表板视觉效果右上角的三点菜单中确认 Quick Sight。

  • 确认 Quick Sight 用户是否具有共享仪表板的查看者角色。

  • 在 API Gateway 中启用 CORS 并重新部署 API。有关更多信息，请参阅 API Gateway 文档。

  • 检查浏览器控制台中是否存在与网络相关的错误 CORS。

“用户无权访问” 错误

可能的原因：

  • 用户的电子邮件未与 Quick Sight 控制面板共享。

  • Quick Sight 中的用户角色或权限不正确。

解决方案：

  1. 在 Quick Sight 控制台上，打开您的控制面板，然后选择 “共享”、“共享控制面板”。

  2. 添加用户的电子邮件地址（与 Amazon Cognito 登录电子邮件相匹配）。

  3. 分配查看者权限角色。

  4. 要求用户注销并重新登录以刷新权限。

相关资源

AWS 文档

教程和视频