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 ：用於產生對話回應的來源文件。

部署此解決方案

先決條件：

在部署此解決方案之前，請確保已設定以下先決條件：

• 有效的 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 許可證獲得許可。請參閱許可證文件。