Merge branch 'develop' v0.1.17

CHANGELOG.md

@@ -5,6 +5,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+## [0.1.17] - 2024-07-08
+- Amazon Q Business Expert plugin now supports Identity Center authentication - PR #30
 
 ## [0.1.16] - 2024-07-02
 ### Added
@@ -89,7 +91,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Initial release
 
 [Unreleased]: https://github.com/aws-samples/qnabot-on-aws-plugin-samples/compare/main...develop
-[0.1.16]: https://github.com/aws-samples/qnabot-on-aws-plugin-samples/releases/tag/v0.1.15
+[0.1.17]: https://github.com/aws-samples/qnabot-on-aws-plugin-samples/releases/tag/v0.1.17
+[0.1.16]: https://github.com/aws-samples/qnabot-on-aws-plugin-samples/releases/tag/v0.1.16
 [0.1.15]: https://github.com/aws-samples/qnabot-on-aws-plugin-samples/releases/tag/v0.1.15
 [0.1.14]: https://github.com/aws-samples/qnabot-on-aws-plugin-samples/releases/tag/v0.1.14
 [0.1.13]: https://github.com/aws-samples/qnabot-on-aws-plugin-samples/releases/tag/v0.1.13

lambdas/qna_bot_qbusiness_lambdahook/README.md

@@ -1,6 +1,6 @@
 # QnABot LambdaHook for Amazon Q Business (preview)
 
-| :zap:        If you have created a new Amazon Q Business application on or after April 30th, 2024, you will not be able to set up a QnAbot LambdaHook for Amazon Q Business using the instructions provided below. This is because new Amazon Q Business applications require integration with IAM Identity Center. We don't currently have a plan to update the plugin to accommodate the setup for new applications created since April 30th, 2024. We'd be delighted to accept a Pull Request from community members if you make it work in the meantime.  |
+| :zap:        The QnAbot LambdaHook for Amazon Q Business has been updated to accomodate migration to IAM Identicy Center. Please note some manual configuration steps are required and outlined below as part of the deployment process. |
 |-----------------------------------------|
 
 Amazon Q is a new generative AI-powered application that helps users get work done. Amazon Q can become your tailored business expert and let you discover content, brainstorm ideas, or create summaries using your company’s data safely and securely. For more information see: [Introducing Amazon Q, a new generative AI-powered assistant (preview)](https://aws.amazon.com/blogs/aws/introducing-amazon-q-a-new-generative-ai-powered-assistant-preview)
@@ -15,26 +15,41 @@ It's pretty cool. It's easy to deploy in your own AWS Account, and add to your o
 
 ## Deploy Amazon Q (your business expert) as a fallback source of answers, using Lambda hooks with CustomNoMatches/no_hits
 
+### Prerequisites 
+
+1. An existing deployment of a Q Business application. Please reference the AWS docs for creating a new [Q Business application](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html)
+2. A deployment of the Lex Web UI with login enabled is required for this stack. To learn more about deploying the Web UI see the [Github repo for the solution](https://github.com/aws-samples/aws-lex-web-ui). This Cognito should be integrated with the same identity provider as your Identity Center (in the below example we will use IAM Identity Center as the IDP).
+3. The Cognito user pool created by the Web UI will need to be added as **Trusted token issuer** to Identity Center by doing the following steps
+    1. Go to Identity Center and click on `Settings`, then `Create trusted token issuer`
+    2. The issuer URL will be `https://cognito-idp.[region].amazonaws.com/[cognito-pool-id]` and you will need to provide which attributes should map between the two.
+        ![Issuer](../../images/token-issuer.PNG)
+4. A custom application will need to be created in Identity Center to handle the connection between your Q Business application and your Cognito pool. Follow these steps to create the application.
+    1. Go to Identity Center and click on `Applications` then `Add application`
+    2. Select `I have an application I want to set up` and `OAuth 2.0` on the next page for Selecting Application type, then hit `Next`
+    3. For `Application URL`, provide the **Web experience URL** of your Q Business application (if you have a custom domain for your Q Business application, you would use the URL of that domain). You can either opt to assign specific users/groups to this application or allow any Identity Center users/groups to access the application. Your Q Business subscriptions will still apply however so only users with a subscription can successfully chat with the application. Then hit `Next`
+    4. Select the Trusted token issuer that was created in Step 2 of this guide, you will now need an aud claim so that the token issuer can identify the application. This aud claim is created when you deploy the Lex Web UI and can be found within the Coginto User pool. To find this value go to your Cognito user pool and select the `App integration` tab and scroll to the bottom. The aud claim is the **Client ID** value found under the App client list. Take this value and paste it into the aud claim field, then select `Next`
+        ![Claim](../../images/aud-claim.PNG)
+    5. You will need to wait until after you deploy the CloudFormation stack to provide the role on the Specify application credentials page. For now, provide any existing IAM role in your environment and hit `Next`.
+
 ### Deploy a new Amazon Q (Business) Plugin stack
 
 Use AWS CloudFormation to deploy one or more of the sample plugin Lambdas in your own AWS account (if you do not have an AWS account, please see [How do I create and activate a new Amazon Web Services account?](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/)):
 
 1. Log into the [AWS console](https://console.aws.amazon.com/) if you are not already.
-*Note: Ensure that your IAM Role/User have permissions to create and manage the necessary resources and components for this application.*
 2. Choose one of the **Launch Stack** buttons below for your desired AWS region to open the AWS CloudFormation console and create a new stack.
 3. On the CloudFormation `Create Stack` page, click `Next`
 4. Enter the following parameters:
     1. `Stack Name`: Name your stack, e.g. QNABOTPLUGIN-QNA-BOT-QBUSINESS-LAMBDAHOOK.
     2. `AmazonQAppId`: Existing Amazon Q Application ID (copy from AWS console)
-    3. `AmazonQUserId`: Amazon Q User ID (leave empty to use authenticated bot users' email as user Id) - see note below
-    4. `AmazonQRegion`: Amazon Q Region (us-east-1, or us-west-2)
-    5. `AmazonQEndpointUrl`: (Optional) Amazon Q Endpoint (leave empty for default endpoint)
-
-*Note on UserId:*  
-You have two options:  
-1. (Default) Map each bot user's email to a Q Business userid. This means that each QnAbot user must be an authenticated user (e.g. logged in via Cognito using Lex Web UI). ACLs will be observed per user. This is the default setup.
-2. (Proxy) Alternatively, when you deploy you can choose a single email to use when QnABot invokes Amazon Q. This removes the need for QnABot users to be authenticated (logged in), but it also means that no per-user ACLs are supported since ACLS will be based on the single proxy userId.
-
+    3. `AmazonQRegion`: Amazon Q Region (us-east-1, or us-west-2)
+    4. `DynamoDBTableName`: DynamoDB table that will be used to cache encrypted user credentials for question answering with QBusiness.
+    5. `IDCApplicationARN`: ARN of the Identity Center customer managed application created for QBusiness (see prerequisites for steps to create)
+5. Launch the stack.
+6. When your QNABOTPLUGIN-QNA-BOT-QBUSINESS-LAMBDAHOOK Plugin CloudFormation stack status is CREATE_COMPLETE, choose the **Outputs** tab. Look for the output `QnAItemLambdaFunctionRoleArn` and modify your existing Identity Center application with this value by following these steps.
+    1. Go to Identity Center and click on `Applications` and find the application created for the QBusiness plugin. Click on the application to view more details.
+    2. Select `Actions->Edit configuration` to modify the settings of the application
+    3. Expand the Application credentials and paste the ARN obtained from the Outputs section.
+    4. Hit `Save changes`
 
 #### <u>N. Virginia (us-east-1)</u>
 Plugin | Launch Stack | Template URL
@@ -47,9 +62,7 @@ Plugin | Launch Stack | Template URL
 QNABOTPLUGIN-QNA-BOT-QBUSINESS-LAMBDAHOOK | [![Launch Stack](https://cdn.rawgit.com/buildkite/cloudformation-launch-stack-button-svg/master/launch-stack.svg)](https://us-west-2.console.aws.amazon.com/cloudformation/home?region=us-west-2#/stacks/create/review?templateURL=https://s3.us-west-2.amazonaws.com/aws-ml-blog-us-west-2/artifacts/qnabot-on-aws-plugin-samples/qna_bot_qbusiness_lambdahook.yaml&stackName=QNABOTPLUGIN-QNA-BOT-QBUSINESS-LAMBDAHOOK) | https://s3.us-west-2.amazonaws.com/aws-ml-blog-us-west-2/artifacts/qnabot-on-aws-plugin-samples/qna_bot_qbusiness_lambdahook.yaml
 
 ## After your Amazon Q Plugin stack is deployed
-Configure QnAbot to prompt Amazon Q directly by configuring the AmazonQ LambdaHook function `QnAItemLambdaHookFunctionName` as a Lambda Hook for the QnABot [CustomNoMatches](https://docs.aws.amazon.com/solutions/latest/qnabot-on-aws/keyword-filters-and-custom-dont-know-answers.html) `no_hits` item. When QnABot cannot answer a question by any other means, it reverts to the `no_hits` item, which, when configured with this Lambda Hook function, will relay the question to Amazon Q.  
-
-***When integrating Amazon Q in this way, you will (almost definately) want to use it instead of using the Kendra/LLM RAG approach, since Amazon Q offers an alternive approach - you are unlikely to need both. Use QnABot Content Designer Settings to remove any Kendra index specified in the setting: `ALT_SEARCH_KENDRA_INDEXES`*** 
+Configure QnAbot to prompt Amazon Q directly by configuring the AmazonQ LambdaHook function `QnAItemLambdaHookFunctionName` as a Lambda Hook for the QnABot [CustomNoMatches](https://docs.aws.amazon.com/solutions/latest/qnabot-on-aws/using-keyword-filters-for.html) `no_hits` item. When QnABot cannot answer a question by any other means, it reverts to the `no_hits` item, which, when configured with this Lambda Hook function, will relay the question to Amazon Q.  
 
 When your QNABOTPLUGIN-QNA-BOT-QBUSINESS-LAMBDAHOOK Plugin CloudFormation stack status is CREATE_COMPLETE, choose the **Outputs** tab. Look for the outputs `QnAItemLambdaHookFunctionName` and `QnAItemLambdaHookArgs`. Use these values in the LambdaHook section of your no_hits item. You can change the value of "Prefix', or use "None" if you don't want to prefix the LLM answer.