使用 Amazon Cognito 和 IaC 自動化將 Amazon Quick Sight 視覺化元件內嵌至 Web 應用程式 IaC - AWS 方案指引
總結先決條件和限制Architecture工具最佳實務史詩疑難排解相關資源

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

使用 Amazon Cognito 和 IaC 自動化將 Amazon Quick Sight 視覺化元件內嵌至 Web 應用程式 IaC

Ishita Gupta 和 Srishti Wadhwa，Amazon Web Services

總結

此模式透過使用已註冊的使用者內嵌搭配簡化的 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 的無伺服器後端

  • 透過 Amazon CloudFront、Amazon Simple Storage Service (Amazon S3) 和 保護前端託管 AWS WAF

  • 使用 Amazon Cognito 進行身分管理

所有元件的設定方式是遵循具有最低權限 AWS Identity and Access Management (IAM) 政策、 AWS WAF 保護和end-to-end加密的安全最佳實務。

此解決方案非常適合希望將安全、互動式分析整合到應用程式中的開發團隊和組織，同時保持對使用者存取的精細控制。解決方案使用 AWS 受管服務和自動化來簡化內嵌程序、增強安全性，並確保可擴展性以滿足不斷變化的業務需求。

目標對象和使用案例：

  • 想要將分析嵌入 React 應用程式的前端開發人員

  • 希望提供每個使用者或以角色為基礎的資料視覺化的軟體即服務 (SaaS) 產品團隊

  • 有興趣將 AWS 分析整合到自訂入口網站的解決方案架構師

  • 商業智慧 (BI) 開發人員想要向已驗證的使用者公開視覺效果，而不需要完整儀表板存取

  • 想要在內部工具中嵌入互動式 Quick Sight 圖表的企業團隊

先決條件和限制

先決條件

若要成功實作此模式，請確定已備妥下列項目：

  • 作用中 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 或已安裝的 yarn

    • Vite 作為 React 建置工具

    • React (19.1.1 版）

  • 儀表板共用 – 儀表板必須在 Quick Sight 中共用，實作器必須登入才能存取內嵌視覺效果或儀表板。

限制

  • 此模式使用已註冊的使用者內嵌方法，這需要實作者擁有作用中的 Quick Sight 帳戶。

  • 存取權僅限於與實作此模式的已驗證 Quick Sight 使用者明確共用的儀表板和視覺效果。如果實作器沒有正確的存取權限，內嵌 URL 產生將會失敗，且視覺效果也不會載入。

  • CloudFormation 堆疊必須部署在支援 Quick Sight、API Gateway 和 Amazon Cognito AWS 區域 的 中。如需區域可用性，請參閱AWS 服務 依區域。

產品版本

Architecture

目標架構

下圖顯示此模式的架構和工作流程。

將 Quick Sight 視覺效果嵌入 React 應用程式的架構和工作流程。

在此工作流程中：

  1. 使用者存取應用程式。使用者使用瀏覽器開啟 React Web 應用程式。請求會路由至 CloudFront 分佈，做為應用程式的內容交付網路。

  2. AWS WAF 會篩選惡意請求。 在請求到達 CloudFront 之前，它會通過 AWS WAF。 會 AWS WAF 檢查流量，並根據安全規則封鎖任何惡意或可疑的請求。

  3. Amazon S3 提供靜態檔案。如果請求是乾淨的，CloudFront 會使用原始存取控制 (OAC) 從私有 S3 儲存貯體擷取靜態前端資產 (HTML、JS、CSS)，並將其交付至瀏覽器。

  4. 使用者登入。載入應用程式後，使用者會透過 Amazon Cognito 登入，以驗證使用者並傳回安全 JSON Web 權杖 (JWT) 進行授權 API 存取。

  5. 應用程式會提出 API 請求。登入後，React 應用程式會對 API Gateway 上的/get-embed-url端點進行安全呼叫，並在請求標頭中傳遞 JWT 字符以進行身分驗證。

  6. 字符已驗證。API Gateway 會使用 Amazon Cognito 授權方來驗證權杖。如果字符有效，則請求會繼續進行；否則，會使用 401 （未授權） 回應拒絕該請求。

  7. 請求會導向 Lambda 進行處理。然後，驗證的請求會轉送到後端 Lambda 函數。此函數負責為請求的 Quick Sight 視覺效果產生內嵌 URL。

  8. Lambda 會從 Quick Sight 產生內嵌 URL。IAM 使用具有適當許可的 IAM 角色來呼叫 Quick Sight GenerateEmbedUrlForRegisteredUser API，以產生安全、使用者範圍的視覺化 URL。

  9. Lambda 會將內嵌 URL 傳回 API Gateway。Lambda 會將產生的內嵌 URL 傳回 API Gateway，做為 JSON 回應的一部分。然後，此回應會準備交付到前端。

  10. 內嵌 URL 會傳送至瀏覽器。內嵌 URL 會傳回瀏覽器做為 API 回應。

  11. 視覺效果會顯示給使用者。 React 應用程式會收到回應，並使用 Quick Sight 內嵌 SDK 將特定視覺效果呈現給使用者。

自動化和擴展

後端和前端部署使用 完全自動化 CloudFormation，可在單一部署中佈建所有必要 AWS 的資源，包括 Amazon Cognito、Lambda、API Gateway、Amazon S3、CloudFront、IAM AWS WAF角色和 Amazon CloudWatch。

此自動化可確保所有環境的基礎設施一致且可重複。所有元件都會自動擴展：Lambda 會根據函數叫用進行調整、CloudFront 全域提供快取的內容，以及 API Gateway 隨傳入請求進行擴展。

工具

AWS 服務

  • Amazon Quick Sight 是一種雲端原生商業智慧服務，可協助您建立、管理和嵌入互動式儀表板和視覺效果。

  • Amazon API Gateway 會管理做為 React 應用程式與後端服務之間橋接器的 APIs。

  • AWS Lambda是一種無伺服器運算服務，此模式用於動態產生安全的 Quick Sight 內嵌 URLs，並根據請求自動擴展。

  • Amazon Cognito 為使用者提供身分驗證和授權，並為 API 存取發行安全字符。

  • Amazon S3 託管此模式的靜態前端資產，並透過 CloudFront 安全地提供服務。

  • Amazon CloudFront 以低延遲提供全球前端內容，並與 整合 AWS WAF 以進行流量篩選。

  • AWS WAF 透過套用安全規則和速率限制，保護 Web 應用程式免於惡意流量。

  • AWS CloudFormation會在單一部署中自動佈建和設定所有應用程式資源。

  • Amazon CloudWatch 會從 Lambda、API Gateway 和 收集日誌和指標， AWS WAF 以進行監控和故障診斷。

開發工具

  • React JS 是一種前端架構，此模式用於建置 Web 應用程式並整合內嵌 Quick Sight 視覺效果。

  • Vite 是一種建置工具，用於快速開發和最佳化 React 應用程式的生產建置。

  • Quick Sight Embedding SDK 有助於將 Quick Sight 視覺效果嵌入 React 應用程式，並實現應用程式和視覺效果之間的無縫互動。

程式碼儲存庫

此模式的程式碼可在 React 儲存庫的 GitHub Amazon Quick Sight 視覺化內嵌中找到。 https://github.com/aws-samples/sample-quicksight-visual-embedding

最佳實務

此模式會自動實作下列安全最佳實務：

  • 使用 Amazon Cognito 使用者集區進行 JWT 型身分驗證，以及選用的多重要素驗證 (MFA)。

  • 使用 Amazon Cognito 授權方保護 APIs，並強制執行所有服務的最低權限 IAM 政策。

  • 實作 Quick Sight 註冊的使用者內嵌，並使用讀取器角色自動佈建使用者。

  • 透過 CloudFront 和 HTTPS 強制執行支援 TLS 1.2 和更新版本的傳輸中加密。

  • 使用 AES-256 for Amazon S3 搭配版本控制和 OAC 加密靜態資料。

  • 使用限流和配額設定 API Gateway 用量計劃。

  • 使用預留並行和環境變數保護來保護 Lambda。

  • 啟用 Amazon S3、CloudFront、Lambda 和 API Gateway 的記錄；使用 CloudWatch 監控 服務。

  • 加密日誌、套用存取控制，並強制執行非 HTTPS 或未加密上傳的拒絕政策。

此外，我們建議下列事項：

  • 使用 CloudFormation 來自動化部署和維護跨環境的一致組態。

  • 確定每個使用者都有正確的 Quick Sight 許可來存取內嵌視覺效果。

  • 使用 Amazon Cognito 授權方保護 API Gateway 端點，並強制執行所有 IAM 角色的最低權限原則。

  • 在環境變數中存放敏感資訊，例如 Amazon Resource Name (ARNs) IDs，而不是硬式編碼。

  • 透過減少相依性並改善冷啟動效能來最佳化 Lambda 函數。如需詳細資訊，請參閱 AWS 部落格文章最佳化搭配 SnapStart AWS Lambda 使用進階入門策略的冷啟動效能。

  • 將您的 CloudFront 網域新增至 Quick Sight 允許清單，以啟用安全的視覺化內嵌。

  • 使用 CloudWatch 和 AWS WAF 來監控記錄、提醒和流量保護的效能和安全性。

其他建議的最佳實務

  • 使用自訂網域搭配來自 的 SSL 憑證 AWS Certificate Manager ，以提供安全且品牌化的使用者體驗。

  • 使用客戶受管 AWS Key Management Service (AWS KMS) 金鑰加密 Amazon S3 資料和 CloudWatch 日誌，以更好地控制加密。

  • 使用地理封鎖、SQL Injection (SQLi)、跨網站指令碼 (XSS) 保護和自訂篩選條件來擴展 AWS WAF 規則，以增強威脅預防。

  • 啟用 CloudWatch 警示 AWS Config，以及 AWS CloudTrail 即時監控、稽核和組態合規。

  • 套用精細的 IAM 政策、強制執行 API 金鑰輪換，並只在絕對必要時才允許跨帳戶存取。

  • 執行定期安全性評估，以確保符合系統和組織控制 2 (SOC 2)、一般資料保護法規 (GDPR) 和健康保險流通與責任法案 (HIPAA) 等合規架構。

史詩

任務Description所需的技能

複製儲存庫。

將此解決方案的 GitHub 儲存庫複製到本機系統，然後導覽至專案目錄：

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

cd sample-quicksight-visual-embedding

此儲存庫包含部署解決方案所需的 CloudFormation 範本和 React 原始程式碼。

應用程式開發人員
任務Description所需的技能

部署 範本。

  1. 登入 AWS 管理主控台 並開啟 AWS CloudFormation 主控台。

  2. 在堆疊頁面上，選擇右上角的建立堆疊，然後選擇使用新資源 （標準）。

  3. 在建立堆疊頁面上，針對先決條件 – 準備範本，選擇選擇現有範本。

  4. 對於 Specify template (指定範本)，選擇 Upload a template file (上傳範本檔案)。

  5. 從本機 GitHub 儲存庫上傳template.yaml檔案，然後選擇下一步。

  6. 在指定堆疊詳細資訊頁面上，輸入堆疊名稱 （例如，quicksight-embedding-stack)。

  7. 在設定堆疊選項頁面上，保留預設設定，然後勾選方塊以確認建立 IAM 資源。選擇下一步。

  8. 在檢閱和建立頁面上，選擇提交。

 如需詳細資訊，請參閱 CloudFormation 文件中的建立和管理堆疊。

AWS 管理員

監控堆疊建立。

在事件索引標籤中監控堆疊，直到其狀態為 CREATE_COMPLETE。

AWS 管理員

擷取堆疊輸出。

  1. 部署完成時，請選擇輸出索引標籤。

  2. 記下金鑰輸出：ApiGatewayUrl、UserPoolId、CloudFrontDomainName、 UserPoolClientId和 S3BucketName。您將在後續步驟中使用此資訊。

AWS 管理員
任務Description所需的技能

擷取 Quick Sight 視覺識別符。

  1. 開啟 Quick Sight 儀表板。

  2. 請注意您計劃嵌入 Web 應用程式中的每個視覺效果的儀表板 ID、工作表 ID 和視覺效果 ID。

Quick Sight 管理員

設定您的本機 React 環境。

若要設定本機 React 環境並將其連結至 AWS 資源，請在本機 GitHub 儲存庫的 my-app/ 資料夾中建立 .env 檔案。將檔案填入：

  • 您的 AWS 區域

  • Amazon Cognito 集區資訊 （來自 CloudFormation 堆疊輸出）

  • API Gateway 端點 （來自 CloudFormation 堆疊輸出）

  • Quick Sight 視覺效果 IDs (DashboardId、SheetId、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
應用程式開發人員
任務Description所需的技能

在 Cognito 中建立或管理使用者

若要啟用已驗證的使用者存取內嵌 Quick Sight 視覺效果，您必須先在 Amazon Cognito 中建立使用者：

  1. 在 Amazon Cognito 主控台上，選擇使用者集區，然後選擇符合的集區 UserPoolId（從 CloudFormation 輸出）。

  2. 將使用者新增至集區。您可以從兩個選項中選擇：

    • 在 Amazon Cognito 中，使用電子郵件地址和臨時密碼手動建立使用者 （如需詳細資訊，請參閱 Amazon Cognito 文件)

      —或—

    • 透過在 my-app/src/auth/AuthWrapper.jsx 檔案中設定 在 UI hideSignUp={false} 中啟用自我註冊。

AWS 管理員

提供 Quick Sight 儀表板存取

若要提供 Quick Sight 視覺效果的存取權，請將檢視者許可存取權提供給已驗證的使用者：

  1. 在 Quick Sight 主控台上，選擇儀表板。

  2. 選擇您要共用的儀表板名稱，以選取其名稱。

  3. 在儀表板頁面的右上角，選擇共用。

  4. 在共用面板中，選擇與特定使用者共用。

  5. 若要新增使用者，請選擇邀請使用者或加號 (＋) 圖示。

  6. 在電子郵件欄位中，輸入收件人的完整電子郵件地址。（此電子郵件必須與使用者的 Amazon Cognito 登入完全相符）

  7. 從電子郵件欄位旁的許可選單中，選擇檢視器。

  8. 若要傳送邀請和授予存取權，請選擇共用。

每個使用者都會收到一封電子郵件，其中包含儀表板的連結。您可以隨時透過共用功能表修改許可。

如需詳細資訊，請參閱《Amazon Quick Suite 文件》中的授予個別 Amazon Quick Sight 使用者和群組對 Amazon Quick Sight 中儀表板的存取權。

Quick Sight 管理員
任務Description所需的技能

安裝相依性並建置專案。

在 React 應用程式目錄中，執行下列命令來產生最佳化的生產檔案：

cd my-app
npm install
npm run build
應用程式開發人員

將建置檔案上傳至 Amazon S3。

將所有檔案從my-app/dist/目錄上傳至由 佈建的 S3 儲存貯體 CloudFormation （請勿上傳資料夾本身）。

應用程式開發人員

建立 CloudFront 無效。

在 CloudFront 主控台上，為部署後/*重新整理快取內容的路徑建立失效。如需說明，請參閱 CloudFront 文件中的使檔案失效。

AWS 管理員
任務Description所需的技能

將 CloudFront 網域新增至 Quick Sight 允許清單。

若要讓您的 CloudFront 網域安全地嵌入 Quick Sight 視覺效果：

  1. 在 Quick Sight 主控台上，選擇管理 Quick Sight、網域和內嵌。

  2. 將 CloudFront 網域新增至網域方塊 （例如 https://d1234567890abc.cloudfront.net)。

  3. 選擇新增網域。

Quick Sight 管理員
任務Description所需的技能

開啟 React 應用程式。

使用 CloudFront 網域 （來自 CloudFormation 輸出） 在瀏覽器中開啟部署的 React Web 應用程式。

應用程式擁有者

驗證身分驗證。

使用 Amazon Cognito 登入資料來登入應用程式，以透過 API Gateway 驗證身分驗證流程和 JWT 驗證。

應用程式擁有者

驗證內嵌視覺效果。

根據使用者特定的存取許可，確認 Quick Sight 視覺效果在應用程式中正確載入。

應用程式擁有者

驗證 API 和 Lambda 連線。

確認應用程式可以成功呼叫 /get-embed-url API 並擷取有效的 Quick Sight 內嵌 URLs而不會發生錯誤。

應用程式擁有者
任務Description所需的技能

使用 CloudWatch 進行監控。

您可以使用可 AWS 觀測性工具來監控應用程式，並在生產環境中維持安全、可擴展的效能。

在 CloudWatch 中檢閱 Lambda 日誌、API Gateway 指標和 Amazon Cognito 身分驗證事件，以確保應用程式運作狀態並偵測異常。

AWS 管理員

Track AWS WAF 和 CloudFront 日誌。

檢查 AWS WAF 日誌是否有封鎖或可疑的請求，以及 CloudFront 存取日誌是否有效能和快取指標。

AWS 管理員

疑難排解

問題解決方案

「不允許網域」錯誤

  1. 在 Quick Sight 主控台上，選擇管理 Quick Sight、網域和內嵌。

  2. 新增您的 CloudFront 網域 （例如 https://d1234567890abc.cloudfront.net)。

  3. 儲存組態並重新載入應用程式。

身分驗證錯誤

可能原因：

  • .env 檔案中的 Amazon Cognito 使用者集區 ID 或應用程式用戶端 ID 不正確。

  • 未在 Amazon Cognito 使用者集區中確認使用者。

  • API 請求中的 JWT 字符無效或缺少。

解決方案：

  • 驗證 .env 檔案中的 Amazon Cognito 組態值。

  • 在 Amazon Cognito 主控台上，檢查使用者索引標籤以確認使用者處於作用中狀態。

  • 確認授權標頭包含有效的 JWT 字符。

  • 在 API Gateway 主控台上，檢查授權方以確認 API Gateway 使用 Amazon Cognito 授權方進行身分驗證。

API Gateway 錯誤

可能原因：

  • API Gateway 中遺失或設定錯誤的 Amazon Cognito 授權方。

  • 呼叫 Quick Sight API 的 Lambda 許可不足。

  • .env 與 CloudFormation 輸出之間的 API URL 不相符。

解決方案：

  • 重新確認 API Gateway 調用 URL 在您的 .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) 組態。

解決方案：

  • 從儀表板視覺效果右上角的三點式功能表中確認 Quick Sight IDs。

  • 確認 Quick Sight 使用者具有共用儀表板的檢視器角色。

  • 在 API Gateway 中啟用 CORS，並重新部署 API。如需詳細資訊，請參閱 API Gateway 文件。

  • 檢查瀏覽器主控台是否有 CORS 的網路相關錯誤。

「使用者沒有存取權」錯誤

可能原因：

  • 使用者的電子郵件並未與 Quick Sight 儀表板共用。

  • Quick Sight 中的使用者角色或許可不正確。

解決方案：

  1. 在 Quick Sight 主控台上，開啟儀表板，然後選擇共用、共用儀表板。

  2. 新增使用者的電子郵件地址 （符合 Amazon Cognito 登入電子郵件）。

  3. 指派檢視器許可角色。

  4. 要求使用者登出並再次登入以重新整理許可。

相關資源

AWS 文件

教學課程和影片