ホーム>プログラミング関連>その他のソースコード
ダウンロード

Amazon Q Business によるカスタム Web エクスペリエンス

⚡ 2024 年 4 月 30 日以降に新しい Amazon Q Business アプリケーションを作成した場合は、以下に提供される更新された手順を使用してカスタム UI をセットアップできるようになりました。

注:このガイドで提供される手順は Cognito に固有のものですが、若干の調整を加えれば他の OIDC 2.0 準拠のアイデンティティ プロバイダー (IdP) でも機能するはずです。

顧客は多くの場合、フィードバックの処理、コーポレートカラーとテンプレートの使用、カスタムログイン、ユーザーインターフェイスを単一のプラットフォームに統合することによるコンテキスト切り替えの削減など、カスタム機能を Amazon Q ユーザーインターフェイスに統合する機能を望んでいます。コードリポジトリでは、ユーザー認証に Amazon Cognito を使用し、chat_sync API を通じてプログラムでチャットボット アプリケーションを呼び出す Amazon Q SDK を使用して、Amazon Q にカスタム UI を統合する方法を示します。

アーキテクチャ図

?‍ ワークフローには次の手順が含まれます。

  1. まずユーザーは、Application Load Balancer の背後でホストされているチャットボット アプリケーションにアクセスします。

  2. ユーザーは Cognito でログインするように求められます

  3. UI アプリケーションは、Cognito からのトークンを、Amazon Q のスコープを持つ IAM Identity Center トークンと交換します。

  4. UI アプリケーションは IAM ロールを引き受け、Secure Token Service (STS) から AWS セッションを取得します。これには、Amazon Q と対話するために IAM Identity Center トークンが追加されています。

    • IAM Identity Center と Idp の間のトークン交換の詳細なフローは、以下のブログ投稿で説明されています。

    ?ブログ1

    ?ブログ 2

  5. Amazon Q は ChatSync API を使用して会話を実行します。 ID 認識セッションのおかげで、Amazon Q はどのユーザーと対話しているかを認識します。

    • リクエストでは次の必須パラメータを使用します。

      1. applicationId : Amazon Q 会話にリンクされた Amazon Q アプリケーションの識別子。

      2. userMessage : 会話内のエンド ユーザー メッセージ。

    • Amazon Q は応答を JSON オブジェクトとして返します (Amazon Q ドキュメントで詳しく説明されています)。以下は応答ペイロードのいくつかのコア属性です。

      1. systemMessage : 会話内で AI が生成したメッセージ

      2. sourceAttributions : 会話応答の生成に使用されるソースドキュメント。RAG (検索拡張生成) では、これは常に、Amazon Q でインデックス付けされているエンタープライズナレッジベースの 1 つ以上のドキュメントを参照します。

このソリューションを導入する

前提条件:

このソリューションを展開する前に、次の前提条件が設定されていることを確認してください。

  • 有効な 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 スタックの起動時にカスタム TLS 証明書を提供しなかった場合、UI にアクセスするとブラウザから警告が表示されることに注意してください。上記の手順では、バックアップとして使用できる自己署名証明書を作成する方法を示していますが、これは運用環境のユースケースには決して推奨されません。

認証局によって検証された TLS 証明書を取得し、それを AWS Certificate Manager にインポートし、AWS CloudFormation スタックを起動するときに参照する必要があります。

自己署名証明書 (開発目的) を使用し続ける場合は、ブラウザの警告ページを通過して続行できるはずです。 Chrome では、「接続はプライベートではありません」というエラー メッセージ (NET::ERR_CERT_AUTHORITY_INVALID) が表示されますが、[詳細] をクリックすると、続行するためのリンクが表示されます。

このソリューションを展開します。

ステップ 1: 次の AWS CloudFormation テンプレートを起動して、Web アプリをホストする EC2 インスタンスを含む ELB 、Cognito ユーザー プール をデプロイします。

スタックに次のパラメータを指定します

•スタック名– CloudFormation スタックの名前 (例: AmazonQ-UI-Demo)

• AuthName – Amazon Cognito ユーザープールに割り当てるグローバルに一意の名前。ドメイン名に cognito、aws、amazon などの予約語が含まれていないことを確認してください。

• CertificateARN – 前のステップで生成された CertificateARN

• IdcApplicationArn – Identity Center 顧客アプリケーション ARN 。信頼されたトークン発行者を使用して IAM Identity Center アプリケーションを作成するには、このスタックの一部として cognito ユーザー プールを作成する必要があるため、最初の実行では空白のままにしておきます。

• PublicSubnetIds – EC2 インスタンスと Application Load Balancer のデプロイに使用できるパブリック サブネットの ID。少なくとも 2 つのパブリック サブネットを選択してください

• QApplicationId – Amazon Q の既存のアプリケーション ID

• VPCId – デモのデプロイに使用できる既存の VPC の ID

CloudFormationパラメータ

?スタックが完了したら、[出力] タブから次のキーをコピーします。

対象者: Identity Center で顧客アプリケーションをセットアップする対象者

RoleArn : Identity Center でトークン交換を設定するために必要な IAM ロールの ARN

TrustedIssuerUrl : ID センターをセットアップするための信頼できる発行者のエンドポイント

URL : streamlit アプリにアクセスするためのロードバランサー URL

ステップ 2: IAM ID センター アプリケーションを作成する

  • AWS IAM Identity Center に移動し、新しいカスタム マネージド アプリケーションを追加します。

    アプリケーションの種類を選択-> OAuth2.0 を選択 -> 次へ

    IAM IDC アプリケーション

    新しいカスタム マネージド アプリケーションを作成するオプションが見つからない場合は、IAM Identity Center を使用して組織を有効にしてください。

  • 画像に示すように、アプリケーション名と説明を入力し、以下のオプションを選択します。

    IAM IDC アプリケーション

  • 次に、信頼できるトークン発行者を作成します

    IAM IDC アプリケーション

  • [発行者 URL] で、ステップ 1 のTrustedIssuerUrlを指定し、発行者名を指定し、マップ属性を電子メールとして保持します。

    IAM IDC アプリケーション

  • 次に、IAM Identity Center アプリケーションの認証設定に戻り、前の手順で作成した信頼できるトークン発行者を選択し [リストに表示されない場合は更新]、Aud クレームを追加し、手順 1 のオーディエンスを指定して、クリックします。次

    IAM IDC アプリケーション

  • [アプリケーション資格情報の指定] で、IAM ロールを入力します -> ステップ 1 のRoleArn を指定します。

    IAM IDC アプリケーション

  • 次に、すべての手順を確認してアプリケーションを作成します。

  • アプリケーションが作成されたら、アプリケーションに移動し、 -> 割り当てられたユーザーとグループ に移動します。

    IAM IDC アプリケーション

  • 次に、ID 伝播用の信頼できるアプリケーションを設定し、以下の手順に従って Amazon Q を ID 伝播用の信頼できるアプリケーションとして設定します。

    IAM IDC アプリケーションIAM IDC アプリケーションIAM IDC アプリケーション

ステップ 4: IAM Identity Center アプリケーションが作成されたら、アプリケーション ARN をコピーし、Cloudformation に移動して、以前に作成したスタックを更新します。パラメーターIdcApplicationArnに ID センター アプリケーション ARN を入力し、スタックを実行します。

CloudFormation 更新スタック

ステップ 5: 更新が完了したら、Cloudformation 出力タブに移動して URL をコピーし、ブラウザで URL を開きます

ステップ 6: Streamlit アプリは、 Cognito に接続するように求めるプロンプトを表示します。最初のログイン試行では、IAM Identity Center に既に存在するユーザーと同じ電子メール ID とパスワードを使用してサインアップを試みます。

⚡ Cognito ユーザー プールと ID センターの両方でユーザーをプロビジョニングする必要をなくすには、以下のリンクに従って ID センターで 2 番目のカスタム アプリ (SAML) を作成します。このカスタム アプリは、Cognito ユーザー プールの ID プロバイダーとして機能します。

?ビデオ

?説明書

AWS Session Manager を介して EC2 に接続します [オプション]: 

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

トラブルシューティング

詳細については、「トラブルシューティング」を参照してください。

安全

詳細については、「貢献」を参照してください。

ライセンス

このライブラリは、MIT-0 ライセンスに基づいてライセンスされています。 LICENSE ファイルを参照してください。

拡大する
追加情報
関連アプリ
おすすめ
関連情報 すべて