Set up a custom plugin on Amazon Q Business and authenticate with Amazon Cognito to interact with backend systems | Amazon Web Services TechTricks365

Businesses are constantly evolving, and leaders are challenged every day to meet new requirements and are seeking ways to optimize their operations and gain a competitive edge. One of the key challenges they face is managing the complexity of disparate business systems and workflows, which leads to inefficiencies, data silos, and missed opportunities.

Generative AI can play an important role in integrating these disparate systems in a secure and seamless manner, addressing these challenges in a cost-effective way. This integration allows for secure and efficient data exchange, action triggering, and enhanced productivity across the organization. Amazon Q Business plays an important role in making this happen. Amazon Q Business enables organizations to quickly and effortlessly analyze their data, uncover insights, and make data-driven decisions. With its intuitive interface and seamless integration with other AWS services, Amazon Q Business empowers businesses of different sizes to transform their data into actionable intelligence and drive innovation across their operations.

In this post, we demonstrate how to build a custom plugin with Amazon Q Business for backend integration. This plugin can integrate existing systems, including third-party systems, with little to no development in just weeks and automate critical workflows. Additionally, we show how to safeguard the solution using Amazon Cognito and AWS IAM Identity Center, maintaining the safety and integrity of sensitive data and workflows. Amazon Q Business also offers application environment guardrails or chat controls that you can configure to control the end-user chat experience to add an additional layer of safety. Lastly, we show how to expose your backend APIs through Amazon API Gateway, which is built on serverless AWS Lambda functions and Amazon DynamoDB.

Solution overview

Amazon Q Business is a fully managed, generative AI-powered assistant that helps enterprises unlock the value of their data and knowledge. With Amazon Q Business, you can quickly find answers to questions, generate summaries and content, and complete tasks by using the information and expertise stored across your company’s various data sources and enterprise systems. At the core of this capability are built-in data source connectors and custom plugins that seamlessly integrate and index content from multiple repositories into a unified index. This enables the Amazon Q Business large language model (LLM) to provide accurate, well-written answers by drawing from the consolidated data and information. The data source connectors act as a bridge, synchronizing content from disparate systems like Salesforce, Jira, and SharePoint into a centralized index that powers the natural language understanding and generative abilities of Amazon Q Business. Amazon Q Business also provides the capability to create custom plugins to integrate with your organization’s backend system and third-party applications.

After you integrate Amazon Q Business with your backend system using a custom plugin, users can ask questions from documents that are uploaded in Amazon Simple Storage Service (Amazon S3). For this post, we use a simple document that contains product names, descriptions, and other related information. Some of the questions you can ask Amazon Q Business might include the following:

• “Give me the name of the products.”
• “Now list all the products along with the description in tabular format.”
• “Now create one of the products .” (At this stage, Amazon Q Business will require you to authenticate against Amazon Cognito to make sure you have the right permission to work on that application.)
• “List all the products along with ID and price in tabular format.”
• “Update the price of product with ID .”

The following diagram illustrates the solution architecture.

The workflow consists of the following steps:

1. The user asks a question using the Amazon Q Business chat interface.
2. Amazon Q Business searches the indexed document in Amazon S3 for relevant information and presents it to the user.
3. The user can use the plugin to perform actions (API calls) in the system exposed to Amazon Q Business using Open API 3.x standards.
4. Because the API is secured with Amazon Cognito, Amazon Q Business requires the user to authenticate against the user credentials available in Amazon Cognito.
5. On successful authentication, API Gateway forwards the request to Lambda.
6. The API response is returned to the user through the Amazon Q Business chat interface.

Prerequisites

Before you begin the walkthrough, you must have an AWS account. If you don’t have one, sign up for one. Additionally, you must have access to the following services:

• Amazon API Gateway
• AWS CloudFormation
• Amazon Cognito
• Amazon DynamoDB
• AWS IAM Identity Center
• AWS Lambda
• Amazon Q Business Pro (This will have an additional monthly cost)
• Amazon S3

Launch the CloudFormation template

Launch the following CloudFormation template to set up Amazon Cognito, API Gateway, DynamoDB, and Lambda resources.

After you deploy the stack, navigate to the Outputs tab for the stack on the AWS CloudFormation console and note the resource details. We use those values later in this post.

If you’re running the CloudFormation template multiple times, make sure to choose a unique name for the stack each time.

Create an Amazon Q Business application

Complete the following steps to create an Amazon Q Business application:

1. On the Amazon Q Business console, choose Applications in the navigation pane.
2. Choose Create application.

3. Provide an application name (for example, product-mgmt-app).
4. Leave the other settings as default and choose Create.

The application will be created in a few seconds.

5. On the application details page, choose Data source.
6. Choose Add an index.
7. For Index name, enter a name for the index.
8. For Index provisioning, select Enterprise or Starter.
9. For Number of units, leave as the default 1.
10. Choose Add an index.

11. On the Data source page, choose Add a data source.
12. Choose Amazon S3 as your data source and enter a unique name.
13. Enter the data source location as the value of BucketName from the CloudFormation stack outputs in the format s3://.

In a later step, we upload a file to this S3 bucket.

14. For IAM role¸ choose Create a new service role (recommended).
15. For Sync scope, select Full sync.
16. For Frequency, select Run on demand.
17. Choose Add data source.
18. On the application details page, choose Manage user access.
19. Choose Add groups and users.
20. You can use existing users or groups in IAM Identity Center or create new users and groups, then choose Confirm.

Only these groups and users have access to the Amazon Q Business application for their subscriptions.

21. Take note of deployed URL of the application to use in a later step.
22. On the Amazon S3 console, locate the S3 bucket you noted earlier and upload the sample document.
23. On the Amazon Q Business console, navigate to the application details page and sync the Amazon S3 data source.

Configure Amazon Cognito

Complete the following steps to set up Amazon Cognito:

1. On the Amazon Cognito console, navigate to the user pool created using the CloudFormation template (ending with-ProductUserPool).
2. Under Branding in the navigation pane, choose Domain.
3. On the Actions menu, choose Create Cognito domain.

We did not create a domain when we created the user pool using the CloudFormation template.

4. For Cognito domain, enter a domain prefix.
5. For Version, select Hosted UI.
6. Choose Create Cognito domain.

7. Under Applications in the navigation pane, choose App clients.
8. Choose your app client.

9. On the app client detail page, choose Login pages and then choose Edit the managed login pages configuration.
10. For URL, enter the deployed URL you noted earlier, followed by /oauth/callback. For example, https://xxxxx.chat.qbusiness.us-east-1.on.aws/oauth/callback.
11. Specify your identity provider, OAuth 2.0 grant type, OpenID Connect scopes, and custom scopes.

Custom scopes are defined as part of the API configuration in API Gateway. This will help Amazon Q Business determine what action a user is allowed to take. In this case, we are allowing the user to read, write, and delete. However, you can change this based on what you want your users to do using the Amazon Q Business chat.

12. Choose Save changes.

13. Take note of the Client ID and Client secret values in the App client information section to use in a later step.

Amazon Cognito doesn’t support changing the client secret after you have created the app client; a new app client is needed if you want to change the client secret.

Lastly, you have to add at least one user to the Amazon Cognito user pool.

14. Choose Users under User management in the navigation pane and choose Create user.
15. Create a user to add to your Amazon Cognito user pool.

We will use this user to authenticate before we can chat and ask questions to the backend system using Amazon Q Business.

Create an Amazon Q Business custom plugin

Complete the following steps to create your custom plugin:

1. On the Amazon Q Business console, navigate to the application you created.
2. Under Actions in the navigation pane, choose Plugins
3. Choose Add plugin.

4. Select Create custom plugin.
5. Provide a plugin name (for example, Products).
6. Under API schema source, select Define with in-line OpenAPI schema editor and enter the following code:

openapi: 3.0.0
info:
  title: CRUD API
  version: 1.0.0
  description: API for performing CRUD operations
servers:
  - url: put api gateway endpoint url here, copy it from cloudformation output
    
paths:
  /products:
    get:
      summary: List all products
      security:
        - OAuth2:
            - products/read
      description: Returns a list of all available products
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Product'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: Create a new product
      security:
        - OAuth2:
            - products/write
      description: Creates a new product
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Product'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /products/{id}:
    get:
      summary: Get a product
      security:
        - OAuth2:
            - products/read
      description: Retrieves a specific product by its ID
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the product to retrieve
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '404':
          description: Product not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      summary: Update a product
      security:
        - OAuth2:
            - products/write
      description: Updates an existing product
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the product to update
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Product'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '404':
          description: Product not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: Delete a product
      security:
        - OAuth2:
            - products/delete
      description: Deletes a specific product by its ID
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the product to delete
          schema:
            type: string
      responses:
        '204':
          description: Successful response
        '404':
          description: Product not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: /oauth2/authorize
          tokenUrl: /oauth2/token
          scopes:
            products/read: read prodcut
            products/write: write prodcut
            products/delete: delete prodcut
  schemas:
    Product:
      type: object
      required:
        - id
        - name
        - description
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
    Error:
      type: object
      properties:
        error:
          type: string

7. In the YAML file, replace the URL value with the value of ProductAPIEndpoint from the CloudFormation stack outputs:

servers url: https://<>.execute-api.us-east-1.amazonaws.com/dev

8. Replace the Amazon Cognito domain URL with the domain you created earlier:

authorizationCode:

authorizationUrl: https://xxxx.auth.us-east1.amazoncognito.com/oauth2/authorize

tokenUrl: https://xxxx.auth.us-east-1.amazoncognito.com/oauth2/token

The YAML file contains the schema (Open API 3.x) that Amazon Q Business uses to decide which API needs to be called based on the description. For example, line 16 in the following screenshot says Return a list all available products, which instructs Amazon Q Business to call this API whenever a user makes a request to list all products.

9. For authentication, select Authentication required.
10. For AWS Secrets Manager secret, choose Create and add new secret and enter the client ID and client secret you saved earlier, and enter the callback URL the same way as you did for the Amazon Cognito host UI (https://<>.chat.qbusiness.<>.on.aws/oauth/callback).
11. For Choose a method to authorize Amazon Q Business, choose Create and use a new service role.
12. Choose Create plugin.

The last step is to enable the chat orchestration feature so Amazon Q Business can select the plugin automatically.

13. On the custom plugin details page, choose Admin controls and guardrails under Enhancements in the navigation pane.
14. In the Global controls section, choose Edit.

15. Select Allow Amazon Q Business to automatically orchestrate chat queries across plugins and data sources, then choose Save.

Configure API Gateway, Lambda, and DynamoDB resources

Everything related to API Gateway, Lambda, and DynamoDB is already configured using the CloudFormation template. Details are available on the Outputs tab of the stack details page. You can also review the details of the Lambda function and DynamoDB table on their respective service consoles. To learn how the Lambda function is exposed as an API through API Gateway, review the details on the API Gateway console.

Chat with Amazon Q Business

Now you’re ready to chat with Amazon Q Business.

1. On the Amazon Q Business console, navigate to your application.
2. Choose the link for Deployed URL.
3. Authenticate using IAM Identity Center (this is to make sure you have access to Amazon Q Business Pro).

You can now ask questions in natural language.

In the following example, we check if Amazon Q Business is able to access the data from the S3 bucket by asking “List all the products and their description in a table.”

After the product descriptions are available, start chatting and ask questions like Can you create product with same description please?. Alternatively, you can create a new product that isn’t listed in the sample document uploaded in Amazon S3. Amazon Q Business will automatically pick the right plugin (in this case, Products).

Subsequent requests for API calls to go through the custom plugin will ask you to authorize your access. Choose Authorize and authenticate with the user credentials created in Amazon Cognito earlier. After you’re authenticated, Amazon Q Business will cache the session token for subsequent API calls and complete the request.

You can query on the products that are available in the backend by asking questions like the following:

• Can you please list all the products?
• Delete a product by ID or by name.
• Create a new product with the name 'Gloves' and description as 'Football gloves' with automatic in-built cooling

Based on the preceding prompt, a product has been created in the products table in DynamoDB.

Cost considerations

The cost of setting up this solution is based on the price of the individual AWS services being used. Prices of those services are available on the individual service pages. The only mandatory cost is the Amazon Q Business Pro license. For more information, see Amazon Q Business pricing.

Clean up

Complete the following steps to clean up your resources:

1. Delete the CloudFormation stack. For instructions, refer to Deleting a stack on the AWS CloudFormation console.
2. Delete the Amazon Q Business application.
3. Delete the Amazon Cognito user pool domain.
4. Empty and delete the S3 bucket. For instructions, refer to Deleting a general purpose bucket.

Conclusion

In this post, we explored how Amazon Q Business can seamlessly integrate with enterprise systems using a custom plugin to help enterprises unlock the value of their data. We walked you through the process of setting up the custom plugin, including configuring the necessary Amazon Cognito and authentication mechanisms.

With this custom plugin, organizations can empower their employees to work efficiently, answers quickly, accelerate reporting, automate workflows, and enhance collaboration. You can ask Amazon Q Business natural language questions and watch as it surfaces the most relevant information from your company’s backend system and act on requests.

Don’t miss out on the transformative power of generative AI and Amazon Q Business. Sign up today and experience the difference that Amazon Q Business can make for your organization’s workflow automation and the efficiency it brings.

About the Authors

Shubhankar Sumar is a Senior Solutions Architect at Amazon Web Services (AWS), working with enterprise software and SaaS customers across the UK to help architect secure, scalable, efficient, and cost-effective systems. He is an experienced software engineer, having built many SaaS solutions powered by generative AI. Shubhankar specializes in building multi-tenant systems on the cloud. He also works closely with customers to bring generative AI capabilities to their SaaS applications.

Dr. Anil Giri is a Solutions Architect at Amazon Web Services. He works with enterprise software and SaaS customers to help them build generative AI applications and implement serverless architectures on AWS. His focus is on guiding clients to create innovative, scalable solutions using cutting-edge cloud technologies.

Ankur Agarwal is a Principal Enterprise Architect at Amazon Web Services Professional Services. Ankur works with enterprise clients to help them get the most out of their investment in cloud computing. He advises on using cloud-based applications, data, and AI technologies to deliver maximum business value.