# Getting started with Amazon Q Business Getting started To start using Amazon Q Business, set up an AWS account and create the necessary AWS Identity and Access Management (IAM) users and roles. To use the AWS Command Line Interface (AWS CLI) or the AWS SDKs, you must install and configure them. After learning about Amazon Q concepts and setting up, you are ready to begin creating your application. **Note** Amazon Q Business does not use customer data for service improvement or for improving underlying LLMs. **Topics** + [ # How Amazon Q Business works ](how-it-works.md) + [ # Key concepts of Amazon Q Business ](concepts-terms.md) + [ # Amazon Q Business subscription tiers and index types ](tiers.md) + [ # Supported document formats in Amazon Q Business ](doc-types.md) + [ # Document attributes in Amazon Q Business ](doc-attributes.md) + [ # Supported languages for Amazon Q Business ](supported-languages.md) + [ # Setting up for Amazon Q Business ](setting-up.md) + [ # IAM roles for Amazon Q Business ](iam-roles.md) # How Amazon Q Business works How Amazon Q Business works With Amazon Q Business, you can build an interactive chat application environment for your organization’s end users, using a combination of your enterprise data and large language model knowledge, or enterprise data only. The following sections outline how Amazon Q works. **Topics** + [ ## Admin workflow ](#admin-flow) + [ ## User workflow ](#user-flow) + [ ## Amazon Q Business workflow ](#app-flow) ## Admin workflow Amazon Q Business uses AWS IAM Identity Center to connect to your workforce users. [Identity Federation through IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers.html#id_roles_providers_iam) is also supported, with the limitations described below. If you're an admin user configuring an Amazon Q Business application, your application creation process depends on whether you're using IAM Identity Center or AWS Identity and Access Management for end user access management. **If IAM Identity Center is already enabled** in your organization, Amazon Q Business will automatically identify it and allow you to connect to it. IAM Identity Center will enable you to manage access based on the users and groups in your corporate directory. It will provide you with accurate billing for the subscriptions of your users and will ensure that your configuration can support the future growth of your Amazon Q Business use cases. **If IAM Identity Center is not yet enabled**, we strongly recommend that you work with your AWS Administrator to [enable an organization instance of IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/idc-setup.html#idc-org-account-setup). This will give your AWS Administrator the most control over the configuration. It will ensure accurate billing for the subscriptions of your users. It will also give you the most flexibility to grow Amazon Q Business use cases, spanning multiple AWS accounts, users, and integrations with other AWS applications. If your AWS Administrator cannot enable an organization instance of IAM Identity Center, you can [enable an account instance of IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/idc-setup.html#idc-account-instance-setup) by yourself through the Amazon Q Business console. Your deployment of Amazon Q Business, and its integration with other AWS applications, will be limited to the AWS Region and AWS account where the IAM Identity Center account instance is enabled. **Note** If you have Amazon Q Business deployments with account instances of IAM Identity Center in multiple AWS accounts, you will be billed separately for user subscriptions per AWS account. For more information, see [Understanding user subscriptions](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tiers.html#managing-sub-tiers). **If you cannot use any IAM Identity Center option**, you can still set up Amazon Q Business using IAM Federation through OIDC (preferred) or SAML. This approach will give your users access to Amazon Q Business capabilities, but will limit your ability to scale Amazon Q Business use cases via integration with other AWS applications. **Note** If you have Amazon Q Business deployments with IAM federation to multiple AWS accounts, you will be billed separately for user subscriptions per AWS account. For more information, see [Understanding user subscriptions](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tiers.html#managing-sub-tiers). The following section outlines the admin workflow for creating applications with IAM Identity Center and Identity Federation through IAM. **Topics** + [ ### Admin workflow for apps using AWS IAM Identity Center ](#admin-flow-idc) + [ ### Admin workflow for apps using Identity Federation through IAM ](#admin-flow-iam) ### Admin workflow for apps using AWS IAM Identity Center Amazon Q Business supports managing end user access to applications using AWS IAM Identity Center. When you use AWS IAM Identity Center to manage users, you sync user identities into IAM Identity Center and connect your Amazon Q Business to IAM Identity Center to manage user access. As an admin user using IAM Identity Center for user management—including integrating an external identity provider to manage user access through IAM Identity Center—you create and configure an Amazon Q Business application environment by completing the following steps: 1. [Enabling an IAM Identity Center instance](https://docs.aws.amazon.com/singlesignon/latest/userguide/get-set-up-for-idc.html) and [connecting the identity source](https://docs.aws.amazon.com/singlesignon/latest/userguide/tutorials.html) for your Amazon Q Business application environment in IAM Identity Center. Amazon Q Business supports both organization and account level IAM Identity Center instances. 1. [Connecting an IAM Identity Center instance](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/idc-setup.html) for your Amazon Q Business application environment with users and groups added. 1. [Creating a fully-configured Amazon Q Business application](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html) that powers your web experience, connected to IAM Identity Center. If you use the console to create an application environment, Amazon Q Business automatically creates a web experience for you, unless you choose not to. If you use the API, you have to create a web experience for your application environment. **Note** When you create an application, you can optionally add groups and users who will be able to access the Amazon Q Business web experience, and then provision the user subscriptions. Or, you can add groups and users when you update your application. An Amazon Q application environment will be created even if you don't add users to it, but an application environment needs to have a subscribed user to work. **Important** Only an admin can create and upgrade user subscriptions. 1. (Optional) [Enhancing the web experience](https://docs.aws.amazon.com/amazonq/latest/business-use-dg/enhancements.html) by adding data sources to it, configuring admin-level controls, tuning chat relevance, plugins, and chat features (including Amazon Q Apps) for end users. For more information, see [Enhancing an Amazon Q Business application environment](https://docs.aws.amazon.com/amazonq/latest/business-use-dg/enhancements.html) and [Amazon Q Business features](https://docs.aws.amazon.com/amazonq/latest/business-use-dg/features.html). 1. (Optional) [Customizing your web experience](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/customizing-web-experience.html) to test how it looks for your end users. In this step, you add a title and subtitle for your web experience, a welcome message, and [quick prompts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/quick-prompts.html) for your end users. You can't chat with—or test—the application environment in customize mode. 1. Then, share the web experience URL generated by Amazon Q Business with the end users you've subscribed so that they can log in and begin chatting. **Note** When you create an application, response generation from large language model (LLM) knowledge is enabled by default. ### Admin workflow for apps using Identity Federation through IAM Amazon Q Business supports managing end user access to applications using [Identity Federation through IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers.html#id_roles_providers_iam). When you use IAM Identity Federation to manage users, your application derives user identities directly from your identity provider. As an admin, you create and configure a Amazon Q Business application environment using IAM Identity Federation by completing the following steps: 1. Configuring your external identity provider and connecting it to an AWS Identity and Access Management identity provider instance. 1. [Creating a fully-configured Amazon Q Business application](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html) that powers your web experience, connected to your identity provider through IAM. You also add subscriptions for end users by adding subscriptions when you create an application. 1. (Optional) [Enhancing the web experience](https://docs.aws.amazon.com/amazonq/latest/business-use-dg/enhancements.html) by adding a data source, configuring admin-level controls, tuning chat relevance, plugins, and chat features (including Amazon Q Apps) for end users. For more information, see [Enhancing an Amazon Q Business application environment](https://docs.aws.amazon.com/amazonq/latest/business-use-dg/enhancements.html) and [Amazon Q Business features](https://docs.aws.amazon.com/amazonq/latest/business-use-dg/features.html). 1. Optionally, [customizing your web experience](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/customizing-web-experience-iam.html) to test how it looks for your end users. In this step, you add a title and subtitle for your web experience, a welcome message, and [quick prompts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/quick-prompts.html) for your end users. You can't chat with—or test—the application environment in customize mode. 1. Then, sharing either your own custom web application URL or the web experience URL generated by Amazon Q Business with the end users you've subscribed so that they can log in and begin chatting. **Note** When you create an application, response generation from large language model (LLM) knowledge is enabled by default. ## User workflow If you're an end user using your organization's Amazon Q Business web experience, you perform the following steps: 1. Navigate to your organization's Amazon Q Business web experience URL, and sign in with your credentials. 1. Start chatting and ask questions of your organization's Amazon Q Business web experience. You can, for example choose from the following options: + **Ask questions** – Ask a question. Amazon Q Business generates and returns answers based on the enterprise data that the end user has access to. Continue the conversation by asking follow-up questions. + **Verify response sources** – Each Amazon Q Business answer cites the source documents used to generate it. + **See conversation history** – Amazon Q Business retains conversation history for 30 days so that they can search through questions and answers. You can view conversation history from the left navigation pane. + **Summarize content** – Amazon Q Business can summarize email message threads. + **Create outlines and drafts** – Use Amazon Q Business to create outlines and templates for documents. + **Perform plugin actions** – If you've configured [Plugins](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/plugins.html), ask Amazon Q Business to perform actions on your behalf, like creating a ticket in a supported third party app. + **Test guardrails and chat controls** – If you've configured [Guardrails and chat controls](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/guardrails.html), check how Amazon Q Business responds to queries and special topics. + Additionally, you can ask Amazon Q Business to complete [any supported follow-up tasks](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/plugins.html)—like [creating task-focused Amazon Q Apps](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/purpose-built-qapps.html)—that your admin has enabled for your application environment. For a list of web experience capabilities, see [Using an Amazon Q web experience](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/using-web-experience.html). 1. Sometimes your question requires information that's beyond the scope of your enterprise data. Then, Amazon Q Business responds that it couldn't find an answer in your documents, unless your admin has allowed Amazon Q Business to [generate responses using model knowledge](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/guardrails.html). Amazon Q Business stores conversation history for 30 days and maintains conversation context after a conversation ends. Conversations can be resumed from where you left off within this 30-day period. ## Amazon Q Business workflow In response to an end user query during a web experience chat, Amazon Q Business does the following: 1. Uses the retriever chosen by the admin to select and retrieve documents that are relevant to the query, following authorization and access control. 1. Generates a response to the user query using either a combination of retrieved enterprise data and model knowledge, or only enterprise data, depending on admin configuration. 1. Returns the generated response to the end user. Amazon Q Business assigns a unique message ID to each answer for tracking purposes. # Key concepts of Amazon Q Business Key concepts This section describes the key concepts and terms related to Amazon Q Business. **Topics** + [ ## Agentic RAG ](#agentic-retrieval-augmented-generation) + [ ## Application environment ](#web-app) + [ ## ACLs (Access Control Lists) ](#acls) + [ ## Amazon Q Apps ](#q-apps) + [ ## Analytics dashboard ](#analytics-dashboard) + [ ## Audio and video extraction ](#audio-video-extraction) + [ ## Browser extensions ](#browser-extensions) + [ ## Chat orchestration ](#chat-orchestration) + [ ## Custom document enrichment ](#cde) + [ ## Data accessors ](#data-accessors) + [ ## Data source ](#data-source) + [ ## Data source connector ](#connector) + [ ## Document ](#document) + [ ## Document attributes ](#doc-attribute) + [ ## Field mappings ](#mappings) + [ ## Filtering using document attributes ](#filtering) + [ ## Foundation model ](#fm) + [ ## Guardrails ](#guardrails) + [ ## Hallucination ](#hallucination) + [ ## Hallucination mitigation ](#hallucination-mitigation) + [ ## IAM Identity Center ](#sso) + [ ## Identity Federation through IAM ](#iam) + [ ## Identity provider ](#idp) + [ ## Index ](#index) + [ ## Index capacity ](#index-units) + [ ## Integrations ](#integrations) + [ ## ISV integration ](#isv-integration) + [ ## Large language model ](#llm) + [ ## Principal Mapping ](#principal-mapping) + [ ## Plugins ](#plugins) + [ ## Quick prompts ](#quick-prompt) + [ ## Response personalization ](#response-personalization) + [ ## Retriever ](#retriever) + [ ## Retrieval Augmented Generation ](#retrieval-augmented-generation) + [ ## Relevance tuning ](#boosting) + [ ## Subscription tiers ](#subscription-tiers) + [ ## Tags ](#tags) + [ ## Visual content extraction ](#visual-content-extraction) + [ ## User store ](#user-store) + [ ## Web experience ](#web-exp) ## Agentic RAG Agentic RAG (Retrieval Augmented Generation) is an advanced natural language processing technique that enhances Amazon Q Business's standard RAG capabilities. Using Agentic RAG, Amazon Q Business employs multiple intelligent agents and specialized tools to process queries and retrieve and generate responses from your enterprise data using its underlying large language model, while continuously monitoring quality. With Agentic RAG system processes queries through a combination of the following coordinated steps: + Analyzes both the user's question and conversation history and determines which retrieval tools to use + Intelligently triggers multiple retrieval operations as needed + Synthesizes information from various sources, and generate responses using its underlying large language model For more information, see [Agentic Retrieval Augmented Generation (RAG)](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/agentic-rag.html). ## Application environment An Amazon Q Business application environment is the primary resource that you use to create a chat solution. To create the application environment, you can use either the Amazon Q Business console or [Amazon Q Business API](https://docs.aws.amazon.com/amazonq/latest/api-reference/Welcome.html) actions. Amazon Q Business offers four distinct methods for creating applications: the standard approach with [IAM Identity Center](https://docs.aws.amazon.com//amazonq/latest/qbusiness-ug/create- application.html) integration, an [IAM federation](https://docs.aws.amazon.com//amazonq/latest/qbusiness-ug/create-application-iam.html) option for AWS-centric environments, an [ anonymous application method](https://docs.aws.amazon.com//amazonq/latest/qbusiness-ug/create-anonymous-application.html) for public-facing scenarios, and a specialized [Quick integration](https://docs.aws.amazon.com//amazonq/latest/qbusiness-ug/create-application- quicksight.html) for analytics-focused implementations. Each creation pathway provides different authentication mechanisms and integration capabilities, allowing organizations to select the most appropriate solution based on their security requirements and existing infrastructure. ## ACLs (Access Control Lists) ACLs control user and system actions for resources. Users can read, write, execute, or modify data based on ACL permissions. ## Amazon Q Apps Amazon Q Business allows web experience users to create lightweight, purpose-built Q Apps to fulfill specific tasks from within their web experience. For example, you can use Amazon Q Business to create an app with a web experience that exclusively generates marketing-related content to improve your marketing team's productivity. Your marketing team members can, in turn, also create their own Amazon Q Apps with its own marketing content-generation capabilities—like writing customer emails and creating promotional content using a certain style of voice, tone, and branding. For more information, see [Amazon Q Apps](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/purpose-built-qapps.html). ## Analytics dashboard The Amazon Q Business analytics dashboard provides comprehensive insights into how users interact with your application. It offers metrics and visualizations on conversation volumes, popular topics, user engagement patterns, and system performance. Administrators can use these analytics to identify trends, understand user needs, measure adoption rates, and make data-driven decisions to improve the application. The dashboard helps track the effectiveness of your Amazon Q Business implementation, identify areas for enhancement, and demonstrate the value it brings to your organization. For more information, see [Using the analytics dashboard](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/analytics-dashboard.html). ## Audio and video extraction Amazon Q Business extracts semantic information from audio and video files, making multimedia content queryable. This allows users to query audio and video content using natural language and explore deeper with follow-up questions, enhancing information retrieval from multimedia sources. For more information, see [Extracting semantic meaning from audio and video content](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/extracting-meaning-from-images.html#Audio-video-extraction). ## Browser extensions The Amazon Q Business browser extension enhances users' web browsing experience by bringing AI-powered assistance directly into their daily workflows. Available for Google Chrome, Microsoft Edge, and Mozilla Firefox browsers, the extension allows users to summarize web pages, ask questions about content, access company knowledge, and use other features available in the Amazon Q Business web experience. This integration requires installation and authentication. For more information, see [Enhancing web browsing with Amazon Q Business](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/browser-extensions.html). ## Chat orchestration Chat orchestration is a Amazon Q Business feature that automatically manages chat requests across configured plugins and data sources. When enabled, Amazon Q Business automatically routes chat requests to plugins, integrating enterprise data and relevant actions within a single chat response. This feature provides unified response integration combining RAG workflow with plugin actions, intelligent action detection for read-only vs. write actions, and smart plugin management with user-driven experience through clarification requests when needed. For more information, see [Chat orchestration settings](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/guardrails-global-controls.html#guardrails-global-orchestration). ## Custom document enrichment Document enrichment is an Amazon Q Business feature that you can use to manipulate your document content and document attributes. You can use document enrichment to perform optical character recognition (OCR) or translation. Document enrichment uses basic and Lambda operations. For more information see, [Document attributes and types](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes.html#doc-attributes) and [Document enrichment](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/custom-document-enrichment.html). ## Data accessors The Amazon Q Business data accessors feature allows you to securely share your enterprise data with verified independent software vendors (ISVs) using Amazon Q. This feature enables ISVs to retrieve relevant content from your Amazon Q index, enhancing their applications with your organization's knowledge. By granting controlled access to your data, you can leverage third-party tools while maintaining security and data access compliance. Data accessors include verified software providers such as Asana, Miro, Zoom, PagerDuty, and Planview. For more information, see [Share your enterprise data with data accessors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/data-accessors.html). ## Data source A data source is a document repository. ## Data source connector A data source connector can crawl and synchronize a data source with an Amazon Q Business index at customizable intervals. Amazon Q Business supports multiple connectors so that you can build your generative AI solution with minimal configuring. For a list of Amazon Q Business supported connectors, see [Supported connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connectors-list.html). For an overview of Amazon Q Business connector features, see [Amazon Q Business data source connector features](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connectors-list.html#connector-key-concepts). ## Document In Amazon Q Business, a document is a unit of data. Specific document formats supported include .csv, .docx, HTML, JSON, .pdf, plaintext, .ppt, .pptx, .rtf, and .xslx. For more information, see [Supported document types](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-types.html). ## Document attributes Document attributes are structural metadata associated with documents, such as document title, document type, and date and time created. Amazon Q Business extracts document attributes during the document ingestion process to provide customizable chat and data manipulation capabilities for your application environment. Amazon Q Business offers reserved document attributes that you can use. Or, you can create custom attributes. For more information, see [Document attributes](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes.html#doc-attributes), [Filtering using document attributes](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/metadata-filtering.html), [Boosting using document attributes](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/metadata-boosting.html), and [Custom document enrichment](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/custom-document-enrichment.html). ## Field mappings An Amazon Q Business index has fields that help you structure data to aid the retrieval process. You can map index fields to your [document attributes](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes.html#doc-attributes) when you add documents directly to an index, or use a data source connector. ## Filtering using document attributes Filtering using document attributes is an Amazon Q Business feature that you can use to filter your Amazon Q Business chat responses for your end user. For example, if you have a document attribute associated with a data source type, you can use the attribute to mandate that chat responses only be generated from a specific data source. For more information, see [Filtering using document attributes](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/metadata-filtering.html). ## Foundation model A foundation model (FM) is a broad, function-based machine learning model (not specific to language systems). An FM is tuned to a large number (billions) of parameters and is trained on a large corpus of documents. ## Guardrails An Amazon Q Business feature that lets you define global controls and topic-level controls for your application environment. Using this feature, you can control what sources your application environment will use to generate responses from, and also control what topics it will respond to and how. For more information, see [Guardrails](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/guardrails.html). ## Hallucination A hallucination, in the machine learning context, is a confident response by an AI application environment that isn't justified by its training data. Think of a hallucination as instances where the response doesn't make sense in the context of the prompt, or when the responses are out of scope with the documents provided. Amazon Q Business offers you the ability to minimize hallucinations by allowing your retrieval system to [generate responses only from your existing enterprise data](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/guardrails.html). ## Hallucination mitigation Hallucination mitigation is a Amazon Q Business feature that checks chat responses for hallucinations and corrects inconsistencies in real-time during chat. If a hallucination is detected with high confidence, Amazon Q Business corrects the inconsistencies in its response and generates a new, edited message. This feature is only available for retrieval augmented generation (RAG) responses from data connected to the application and is not supported for chat orchestration, plugin workflows, or responses generated from tabular data or multimedia transcripts. For more information, see [Response settings](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/guardrails-global-controls.html#guardrails-global-response). ## IAM Identity Center You can manage user access to your Amazon Q Business application environment using IAM Identity Center as your AWS gateway to the identity provider of your choice. For more information on creating an Amazon Q Business application environment integrated with IAM Identity Center see [Configuring an IAM Identity Center instance](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/idc-setup.html) and [Configuring an Amazon Q Business application](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html). For more information about using IAM Identity Center to manage access to applications, see [Manage access to applications](https://docs.aws.amazon.com/singlesignon/latest/userguide/manage-your-applications.html) in the IAM Identity Center User Guide. ## Identity Federation through IAM Amazon Q Business supports identity federation through AWS Identity and Access Management. When you use identity federation, you can manage users with your enterprise identity provider (IdP) and use AWS Identity and Access Management to authenticate users when they sign in to AWS Identity and Access Management. For more information on creating an Amazon Q Business application environment integrated with AWS Identity and Access Management see [Configuring an Amazon Q Business application](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html). ## Identity provider An identity provider (IdP) is a service that stores, manages, maintains, and verifies user identities for your application environment (in this case, Amazon Q Business). Some examples of IdPs are IAM Identity Center, Okta, and Microsoft EntraID (formerly Azure Active Directory). ## Index An index is a corpus of documents. Amazon Q Business supports its own index where you can add and sync documents. An index has fields that you can map your document attributes to, to enhance your end user's chat experience. Amazon Q Business creates retriever for you when it creates your Amazon Q Business index. Amazon Q Business provides two types of index: Enterprise and Starter. You can also use an Amazon Kendra index as a retriever for your generative AI application environment. ## Index capacity When you use an Amazon Q Business native index for your application environment, you must provision data storage capacity for it. Amazon Q Business provides two types of index: Enterprise and Starter. Both index types include 20,000 documents or 200 MB of total extracted text (whichever is reached first) and 100 hours of data connector usage (time that it takes to scan and index new, updated, or deleted documents) by default. For more information, see [Amazon Q Business Index types](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tiers.html#index-tiers) and [Pricing for subscriptions and indices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tiers.html#pricing-subs-index). ## Integrations Amazon Q Business integrations enhance user productivity by bringing AI-powered assistance directly into daily workflows through third-party enterprise tools. These integrations include browser extensions for Google Chrome, Microsoft Edge, and Mozilla Firefox browsers, as well as applications for Slack, Microsoft Teams, Microsoft Outlook, and Microsoft Word. Each integration must be configured and deployed to bring Amazon Q Business capabilities directly within those enterprise tools, allowing users to access Amazon Q's knowledge without context switching during their work. For more information, see [Integrations](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/integrations.html). ## ISV integration Amazon Q Business enables independent software vendors (ISVs) to leverage customer enterprise data through the Amazon Q index to enhance their applications with generative AI capabilities. ISVs can access this data through two methods: either by being added as a data accessor to an existing customer's Amazon Q index, or by creating a Amazon Q application on behalf of the customer. The `SearchRelevantContent` API operation allows ISVs to retrieve relevant content from the customer's data sources while maintaining security and access controls, ensuring users only see content they have permission to access. This integration enables software providers to build enhanced application experiences without having to directly connect to or index individual data sources. For more information, see [Amazon Q index for independent software vendors (ISVs)](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/isv.html). ## Large language model A large language model (LLM) is a language-based, machine learning model that's tuned to a large number (billions) of parameters and trained on a large corpus of documents. ## Principal Mapping Principal mapping is used to connect users and groups with their user ids and group membership information in data sources connected to the application. ## Plugins Amazon Q Business includes a plugins feature that you can use to interact with third-party services such as Jira and Salesforce. With the plugins feature, you can perform actions specific to that service (like creating a ticket) from within your Amazon Q Business web experience chat. For more information, see [Plugins](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/plugins.html). ## Quick prompts The Amazon Q Business quick prompts feature helps with end user discoverability of the web experience chat features. Use this feature to prompt your end user to engage with their web experience chat in specific ways. For example, you can show the available [configured plugins ](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/querying-structured-data.html) or inform users that they can choose to summarize their chat. ## Response personalization Response personalization is a Amazon Q Business feature that customizes chat responses to end users based on metadata associated with them—specifically address and job-related information—in your SSO instance. This feature enhances the relevance of responses by tailoring them to the user's specific context within the organization. To use response personalization effectively, you must have already added the necessary user information in your SSO instance. For more information, see [Response settings](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/guardrails-global-controls.html#guardrails-global-response). ## Retriever A retriever pulls data from an index in real time during a conversation. Amazon Q Business supports a native index retriever and also a Amazon Kendra index retriever. ## Retrieval Augmented Generation Retrieval Augmented Generation (RAG) is a natural language processing (NLP) technique. Using RAG, generative artificial intelligence (generative AI) is conditioned on specific documents that are retrieved from a dataset. Amazon Q Business has a built-in RAG system. A RAG model has the following two components: + A *retrieval* component retrieves relevant documents for the user query. + A *generation* component takes the query and the retrieved documents and then generates an answer to the query using a large language model. ## Relevance tuning You can choose to use document attributes to boost and tune the relevance of chat responses for end users from specific content. For example, if you have a document attribute associated document creation or updating date, you use these attributes to boost chat responses from more recently created or updated documents. For more information, see [Relevance tuning](https://docs.aws.amazon.com/amazonq/latest/business-use-dg/metadata-boosting.html). ## Subscription tiers Amazon Q Business offers multiple user subscription tiers and index types that can be combined to meet your organization's needs. User subscription tiers determine the features available to end users, with both Lite and Pro tier users having access to browser extensions. Index types include starter index and enterprise index, each with different capabilities and storage capacities. You can choose any combination of index types and user subscriptions for your Amazon Q Business application. For more information, see [Amazon Q Business subscription tiers and index types](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tiers.html). **Important** Amazon Q Business Pro tier subscriptions in Europe (Ireland) (eu-west-1) and Asia Pacific (Sydney) (ap-southeast-2) regions are available with a limited set of features. ## Tags Manage your Amazon Q Business applications and data sources by assigning tags or labels. You can use tags to categorize your Amazon Q Business resources in various ways. For example, categorize by purpose, owner, or application environment, or any combination. Each tag consists of a key and a value, both of which you define. For more information, see [Tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tagging.html). ## Visual content extraction When Amazon Q Business processes your input files from a data source, it uses advanced image understanding capabilities to extract semantic information and insights from images and other visuals. This feature makes visual information in your data sources queryable, allowing end users to find relevant information even when it's conveyed in embedded diagrams, charts, or technical illustrations. Visual content extraction provides additional context and nuance to the information in your data sources and builds a more complete knowledge base from your enterprise data. For more information, see [Extracting semantic meaning from embedded visual content](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/extracting-meaning-from-images.html). ## User store User Store is an Amazon Q Business data source connector feature that streamlines user and group management across all the data sources attached to your application environment. For more information about how this feature works and implementation details, see [Understanding User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html). ## Web experience An Amazon Q Business web experience is the chat interface that you create using your Amazon Q Business application environment. Then, your end users can chat with your organization’s Amazon Q Business web experience. You can configure and customize your Amazon Q Business web experience using either the Amazon Q Business console or the Amazon Q Business API. For more information, see [Customizing your web experience](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/customize-web-experience.html). # Amazon Q Business subscription tiers and index types Subscription tiers and index types Amazon Q Business offers multiple index types and user subscription tiers. You can choose any combination of index types and user subscriptions for your Amazon Q Business application environment. **Topics** + [ ## Index types ](#index-tiers) + [ ## User subscription tiers ](#user-sub-tiers) + [ ## Understanding user subscriptions ](#managing-sub-tiers) + [ ## Pricing ](#pricing-subs-index) ## Index types Amazon Q Business offers two types of indexes: starter index and enterprise index. Each index type has different capacity limits measured in index units, which determine the amount of data storage and processing capacity available for your index. For detailed information about index units and capacity, see [Index capacity](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/concepts-terminology.html#index-units). The following table outlines the features of both index types. **** | Starter index | Enterprise index | | --- | --- | | **Ideal use case** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tiers.html) **Features** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tiers.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tiers.html) | **Ideal use case** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tiers.html) **Features** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tiers.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tiers.html) | \$1For reference, 5 pages of text that contain approximately 500 words on each page is equivalent to 10 KB of total extracted text. For detailed pricing information, including examples of charges for index capacity, subscribing and unsubscribing users to Amazon Q Business tiers, upgrading and downgrading Amazon Q Business tiers, and more, see [Amazon Q Business Pricing](https://aws.amazon.com/q/business/pricing). ## User subscription tiers Amazon Q Business offers two subscription tiers: the Amazon Q Business Lite Plan and the Amazon Q Business Pro Plan. The following table outlines the features of Amazon Q Business Pro and Amazon Q Business Lite. **Important** Amazon Q Business Pro tier subscriptions in Europe (Ireland) (eu-west-1) and Asia Pacific (Sydney) (ap-southeast-2) regions are available with a limited set of features. **Important** As of July 1, 2024, Amazon Q Apps only available to Amazon Q Business Pro users. Users with Lite subscriptions should upgrade to Amazon Q Business Pro. **Topics** + [ ### Amazon Q Business Lite users must upgrade to Amazon Q Business Pro to continue using Q Apps ](#lite-user-changes) **** | Amazon Q Business Lite Plan | Amazon Q Business Pro Plan | | --- | --- | | **Ideal use case** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tiers.html) **Features** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tiers.html) **Note:** Built-in and custom plugins are not available with the Lite Plan. Users must upgrade to the Pro Plan to access plugin functionality. | **Ideal use case** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tiers.html) **Features** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tiers.html) | For detailed pricing information, including examples of charges for index capacity, subscribing and unsubscribing users to Amazon Q Business tiers, upgrading and downgrading Amazon Q Business tiers, and more, see [Amazon Q Business Pricing](https://aws.amazon.com/q/business/pricing). ### Amazon Q Business Lite users must upgrade to Amazon Q Business Pro to continue using Q Apps As of July 1, 2024, Amazon Q Apps are available only to [Amazon Q Business Pro users](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tiers.html#managing-sub-tiers). Amazon Q Business Lite users will no longer be able to create, run, or view Q Apps. To access, Q Apps, Lite users must upgrade to Amazon Q Business Pro. As of August 30, 2024, all Amazon Q Apps created by Lite users who did not upgrade their account to Amazon Q Business Pro have been deleted. ## Understanding user subscriptions User subscriptions are created per Amazon Q Business application or Quick account. Each admin can manage subscriptions for users for their specific Amazon Q Business application or Quick account. For applications using IAM Identity Center, AWS will deduplicate subscriptions across all Amazon Q Business applications and Quick accounts, and charge each user only once for their highest subscription level. Note that deduplication will apply only if the Amazon Q Business applications and Quick accounts share the same IAM Identity Center instance. Users subscribed to Amazon Q Business applications using Identity Federation through IAM (IAM Federation), will be charged once per OIDC or SAML IAM Identity Provider. For example, if a user is subscribed to five different Amazon Q Business applications all associated with the same IAM Identity Provider, that user will be charged once. However, if the Amazon Q Business applications are associated with five IAM Identity Providers, the user will be charged five times. In scenarios where a user is subscribed to a mix of applications, the charging structure is as follows: + For applications using IAM Identity Center, users will be charged once across all these applications that share the same IAM Identity Center instance. + For applications using IAM Federation, users will be charged once per IAM Identity Provider. User subscriptions are prorated when created or upgraded based on the number of days left in the calendar month. Any cancellations or downgrades are not prorated and apply starting in the next calendar month. The charges for user subscription starts only after first use by the user. After a user's first use, subscription charges will continue each month until the user's subscriptions have been removed. For a consolidated view of all your user subscriptions see the [Amazon Q subscriptions page](https://console.aws.amazon.com/amazonq/subscriptions). Subscriptions can only be viewed centrally and *not* be created or updated from the Amazon Q subscription management console. ## Pricing You are charged for user subscriptions to application environments and for index capacity. You can choose any combination of the following subscription tiers and indices for your application environment. For detailed pricing information, including examples of charges for index capacity, subscribing and unsubscribing users to Amazon Q Business tiers, upgrading and downgrading Amazon Q Business tiers, and more, see [Amazon Q Business Pricing](https://aws.amazon.com/q/business/pricing). # Supported document formats in Amazon Q Business Supported document formats When you add documents to an Amazon Q Business application environment ([directly](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/upload-docs.html) or through [data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connectors-list.html)) using the console or the API, Amazon Q Business extracts document content and internally parses these to optimize chat responses. During this ingestion, there are file size limits depending on the file type. Video files have a limit of up to 10 GB/10,240 MB. Audio files have a 2 GB/2,048 MB limit. PDF/Word/Powerpoint documents have a 500 MB limit. Excel and other supported file formats have a 50 MB limit. There are also limits to the amount of text extracted from these documents. CSV and Excel have a extracted text limit of 10MB, all other document formats have a limit of 30MB of extracted text. When you upload documents directly into chat using the [Upload files and chat](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/upload-chat-files.html) feature, the size of each file you upload must be 10 MB or less, and 3.75 MB or less for images. The total parsed content for all files combined has to be under 665,000 characters. For images, chat now supports direct uploads of JPEG, JPG, and PNG files. These images can be used for summarizing information and answering questions. Additionally, if you’re uploading Comma Separated Values (CSV) or Microsoft Excel (XLS and XLSX) documents directly into chat, Amazon Q Business performs best for tables with up to 4 columns and 10 rows. Files indexed by an Amazon Q Business data source connector or uploaded directly have no such restrictions. When you directly add files to Amazon Q Business using the [Using direct document upload](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/upload-docs.html) or the [Upload files and chat](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/upload-chat-files.html) feature, it considers each file you add a document. When you connect Amazon Q Business to a data source, what Amazon Q Business considers—and crawls—as a document varies by connector. Along with specific formats like PDF, Word, for example, each enterprise data source also has different entities that it considers documents. To learn about supported entity types for each data source, see [What is a document?](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-doc-crawl.html). For some file types (indicated in the table below), Amazon Q Business can extract semantic information and insights from various types of images embedded in the documents. You can enable content extraction when you add or update a data connector, or when you import a file directly. For more information see [Extracting semantic meaning from embedded visual content with Amazon Q Business](extracting-meaning-from-images.md). **Topics** + [ ## Supported document types ](#doc-types-supported) ## Supported document types The following table shows the document formats that Amazon Q Business supports. **Note** Provide a description of the file as metadata to improve retrieval accuracy. For more information, see [Configuring metadata controls in Amazon Q Business.](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/mapping-doc-attributes.html) | Document format | How document is treated | | --- | --- | | Portable Document Format (PDF) | If you're using a data source connector, or directly uploading documents into your application, Amazon Q can use optical character recognition (OCR) to convert images of typed, handwritten, or printed text into machine-readable text. If enabled, Amazon Q Business can extract semantic information and insights from images and other visuals. The maximum number of pages per PDF for optical character recognition (OCR) or insight extraction from embedded visual elements is 3000 pages. If your PDF is more than 3000 pages, only plaintext is extracted. If you're directly uploading documents into chat, PDFs are converted to HTML, and only plaintext is extracted. | | HyperText Markup Language (HTML) | HTML tags are filtered out to extract plaintext. Content must be between the main HTML start and closing tags (content). | | Extensible Markup Language (XML) | XML tags are filtered out and plaintext is extracted. | | Extensible Stylesheet Language Transformations (XSLT) | Tags are filtered out to extract plaintext. | | Markdown (MD) | Content is extracted as plaintext with Markdown syntax retained. | | Comma Separated Values (CSV) | Content is extracted as plaintext from each cell, with a single file treated as a single document result. You can improve answer accuracy on CSVs by providing a [ metadata file](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/mapping-doc-attributes.html). Example: 
"Attributes":{
    "description":  "A description of your CSV table, a short paragraph providing details about what the use case is and insights you can derive from it.",
    "_document_title": "document title",
    "_file_type": "CSV"
}
| | Microsoft Excel (XLS and XLSX) | Content is extracted as plaintext from each cell, with a single file treated as a single document result. | | JavaScript Object Notation (JSON) | Content is extracted as plaintext with JSON syntax retained. | | Rich Text Format (RTF) | RTF syntax is filtered out to extract plaintext content. | | Microsoft PowerPoint (PPT, PPTX) | By default, only plaintext content is extracted from PowerPoint slides for ingestion. If enabled, Amazon Q Business can extract semantic information and insights from images and other visuals. Otherwise, images and other content aren't extracted. | | Microsoft Word (DOCX) | By default, only plaintext content is extracted from Word pages for ingestion. If enabled, Amazon Q Business can extract semantic information and insights from images and other visuals. Otherwise, images and other content aren't extracted. | | Plain text (TXT) | All text in the text document is extracted. | | Google Slides | By default, only plaintext content is extracted from Google Slides pages for ingestion. If enabled, Amazon Q Business can extract semantic information and insights from images and other visuals. Otherwise, images and other content aren't extracted. | | Google Docs | By default, only plaintext content is extracted from Google Docs pages for ingestion. If enabled, Amazon Q Business can extract semantic information and insights from images and other visuals. Otherwise, images and other content aren't extracted. | # Document attributes in Amazon Q Business Document attributes and types Every document has structural attributes—or metadata—attached to it. Document attributes can include information such as document title, document author, time created, time updated, and document type. You can map document attributes to fields in your Amazon Q Business index. Once mapped to document attributes, these index fields can be used by admin to boost results from specific sources, or by end users to filter and scope their chat results to specific data. **Note** Filtering using document attributes in chat is only supported through the API. Boosting search results using document attributes is supported on both the console and the API. You can also use document attributes to prepare your data for—and customize and control—end user chat. To learn more, see [Filtering using metadata](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/metadata-filtering.html), [Document enrichment in Amazon Q Business](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/custom-document-enrichment.html), [Metadata controls](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/mapping-doc-attributes.html), and [Metadata boosting](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/metadata-boosting.html). **Topics** + [ ## Types of document attributes ](#doc-attribute-types) + [ ## Mapped document attributes ](#mapped-doc-attribute-types) + [ ## Document attribute data types ](#doc-attribute-data-types) ## Types of document attributes Amazon Q Business supports two types of document attributes: reserved or default, and custom. Reserved or default document attributes are provided by Amazon Q Business to map commonly occurring document attributes to index fields. Custom attributes, on the other hand, can be used to map document attributes unique to your content to index fields. Both reserved and custom document attributes can be used to customize end user chat experience. **Important** You can create and map up to 50 document attributes to index fields. Once created, you can't delete or rename any attributes. The following section outlines the available document attributes. **Topics** + [ ### Reserved document attributes ](#reserved-doc-attributes) + [ ### Custom document attributes ](#custom-doc-attributes) ### Reserved document attributes Amazon Q Business offers the following reserved document attributes or index fields that you can map your metadata to: + `_authors` – A list of one or more authors responsible for the content of the document. + `_category` – A category that places a document in a specific group. + `_created_at` – The date and time in ISO 8601 format that the document was created. For example, 2012-03-25T12:30:10\$101:00 is the ISO 8601 date-time format for March 25, 2012 at 12:30 PM (plus 10 seconds) in Central European Time. + `_data_source_id` – The identifier of the data source that contains the document. + `_document_body` – The content of the document. + `_document_id` – A unique identifier for the document. + `_document_title` – The title of the document. + `_file_type` – The file type of the document, such as .pdf or .docx. + `_last_updated_at` – The date and time in ISO 8601 format that the document was last updated. For example, 2012-03-25T12:30:10\$101:00 is the ISO 8601 date-time format for March 25, 2012 at 12:30 PM (plus 10 seconds) in Central European Time. + `_source_uri` – The URI where the document is available. For example, the URI of the document on a company website. + `_version` – An identifier for the specific version of a document. + `_view_count` – The number of times that the document has been viewed. + `_language_code (String)` – The code for a language that applies to the document. This defaults to English if you don't specify a language. + ` _data_source_type` – An **optional** type of data source that contains the document, specified as a text identifier (for example, "Amazon S3" or "WEBCRAWLERV2"). In addition to these default attributes, each Amazon Q Business data source connector also automatically creates specific reserved or default attributes based on commonly occurring metadata in the data source you're using. You can choose to map these to Amazon Q Business index fields when you configure a data source. You can't edit these default attributes. ### Custom document attributes You can create custom attributes based on your own enterprise data. You can map the custom attributes to index fields for a more tailored end user chat experience. For example, you can create a custom attribute called "Department" with the values of "HR", "Sales", and "Manufacturing" and map it an index field. Then, you can use these fields or attributes to allow your end users to filter their chat results to documents in the "HR" department, or restrict response generation to specific data stores. You can also create and map custom document attributes based on uniquely occurring metadata in your data when you connect and configure a Amazon Q Business data source connector. If a document attribute in your data source doesn't have a default attribute mapping already available, or if you want to map additional document attributes to index fields, you can use these custom field mappings to specify how a data source attribute maps to an Amazon Q Business index field. You create and map custom document attributes to index fields by editing your data source after your application environment and retriever are created. ## Mapped document attributes When a document attribute—reserved or custom—is mapped to an index field, you can choose how the field will be used during chat. You can currently configure index fields to perform the following action: + **Searchable** – Allows end users the ability to search data with the specified attributes. **Important** You can mark up to 30 index fields searchable. ## Document attribute data types Document attributes—reserved or custom—can only be the data types that are shown in the following table. Additionally, document attributes can be used to perform the operations outlined. | Data type | Searchable | Filterable | Boostable | | --- | --- | --- | --- | | Date | Yes | Yes | Yes | | Number | Yes | Yes | Yes | | String | Yes | Yes | Yes | | String list | Yes | Yes | Yes | **Note** You can’t change an index field type after it has been created. For more information on filtering and boosting using document attributes, see [Filtering using document-attributes](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/metadata-filtering.html) and [Boosting using document attributes](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/metadata-boosting.html). # Supported languages for Amazon Q Business Supported languages Amazon Q Business is optimized to respond in English. Amazon Q Business only indexes English language documents when you [connect a Amazon Q Business data source](https://docs.aws.amazon.com/amazonq/latest/business-use-dg/data-sources.html) or [directly upload documents](https://docs.aws.amazon.com/amazonq/latest/business-use-dg/upload-docs.html) into your application. We recommend indexing only English language content. # Setting up for Amazon Q Business Setting up Before you begin using Amazon Q Business for the first time, complete the following tasks. **Topics** + [ ## Initial AWS account setup ](#initial-account-setup) + [ ## (Optional) Install the AWS CLI ](#cli-install-setup) + [ ## (Optional) Set up the AWS SDKs ](#service-sdk-setup) + [ ## Consider AWS Regions and endpoints ](#service-endpoints) + [ ## Set up required permissions ](#permissions) ## Initial AWS account setup ### Sign up for an AWS account If you do not have an AWS account, complete the following steps to create one. **To sign up for an AWS account** 1. Open [https://portal.aws.amazon.com/billing/signup](https://portal.aws.amazon.com/billing/signup). 1. Follow the online instructions. Part of the sign-up procedure involves receiving a phone call or text message and entering a verification code on the phone keypad. When you sign up for an AWS account, an *AWS account root user* is created. The root user has access to all AWS services and resources in the account. As a security best practice, assign administrative access to a user, and use only the root user to perform [tasks that require root user access](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html#root-user-tasks). AWS sends you a confirmation email after the sign-up process is complete. At any time, you can view your current account activity and manage your account by going to [https://aws.amazon.com/](https://aws.amazon.com/) and choosing **My Account**. ### Create a user with administrative access After you sign up for an AWS account, secure your AWS account root user, enable AWS IAM Identity Center, and create an administrative user so that you don't use the root user for everyday tasks. **Secure your AWS account root user** 1. Sign in to the [AWS Management Console](https://console.aws.amazon.com/) as the account owner by choosing **Root user** and entering your AWS account email address. On the next page, enter your password. For help signing in by using root user, see [Signing in as the root user](https://docs.aws.amazon.com/signin/latest/userguide/console-sign-in-tutorials.html#introduction-to-root-user-sign-in-tutorial) in the *AWS Sign-In User Guide*. 1. Turn on multi-factor authentication (MFA) for your root user. For instructions, see [Enable a virtual MFA device for your AWS account root user (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/enable-virt-mfa-for-root.html) in the *IAM User Guide*. **Create a user with administrative access** 1. Enable IAM Identity Center. For instructions, see [Enabling AWS IAM Identity Center](https://docs.aws.amazon.com//singlesignon/latest/userguide/get-set-up-for-idc.html) in the *AWS IAM Identity Center User Guide*. 1. In IAM Identity Center, grant administrative access to a user. For a tutorial about using the IAM Identity Center directory as your identity source, see [ Configure user access with the default IAM Identity Center directory](https://docs.aws.amazon.com//singlesignon/latest/userguide/quick-start-default-idc.html) in the *AWS IAM Identity Center User Guide*. **Sign in as the user with administrative access** + To sign in with your IAM Identity Center user, use the sign-in URL that was sent to your email address when you created the IAM Identity Center user. For help signing in using an IAM Identity Center user, see [Signing in to the AWS access portal](https://docs.aws.amazon.com/signin/latest/userguide/iam-id-center-sign-in-tutorial.html) in the *AWS Sign-In User Guide*. **Assign access to additional users** 1. In IAM Identity Center, create a permission set that follows the best practice of applying least-privilege permissions. For instructions, see [ Create a permission set](https://docs.aws.amazon.com//singlesignon/latest/userguide/get-started-create-a-permission-set.html) in the *AWS IAM Identity Center User Guide*. 1. Assign users to a group, and then assign single sign-on access to the group. For instructions, see [ Add groups](https://docs.aws.amazon.com//singlesignon/latest/userguide/addgroups.html) in the *AWS IAM Identity Center User Guide*. ## (Optional) Install the AWS CLI The AWS Command Line Interface (AWS CLI) is a unified developer tool for managing AWS services, including Amazon Q Business. 1. To install the AWS CLI, follow the instructions in [Installing the AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/installing.html) in the *AWS Command Line Interface User Guide*. 1. To configure the AWS CLI and set up a profile to call the AWS CLI, follow the instructions in [Configuring the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html) in the *AWS Command Line Interface User Guide*. 1. To confirm that the AWS CLI profile is configured, run the following command: ``` aws configure ––profile default ``` If your profile has been configured correctly, you will see output similar to the following: ``` AWS Access Key ID [****************52FQ]: AWS Secret Access Key [****************xgyZ]: Default region name [us-west-2]: Default output format [json]: ``` 1. To verify that the AWS CLI is configured for use with Amazon Q Business, run the following commands: ``` aws qbusiness help ``` If the AWS CLI is configured correctly, you will see a list of the supported AWS CLI commands for Amazon Q Business, Amazon Q Business runtime, and Amazon Q Business events. ## (Optional) Set up the AWS SDKs Download and install the AWS SDKs that you want to use. This guide provides examples for Python. For information about other AWS SDKs, see [Tools for Amazon Web Services](https://aws.amazon.com/tools/). The package for the Python SDK is called *Boto3*. Before you run the following Python commands, you must first download and install [Python 3.6 or later](https://www.python.org/downloads/) for your operating system. Support for Python 3.5 and earlier is deprecated. If you don't have pip included in your Python Scripts directory, you can download [get-pip.py](https://bootstrap.pypa.io/get-pip.py) and store this in your Scripts directory. You can also set your Python directory as a [Path or environment variable](https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH) using a terminal program. To install Python, complete the following steps: ``` # Install the latest Boto3 release via pip pip install boto3 # You can install a specific version of Boto3 for compatibility reasons # Install Boto3 version 1.0 specifically pip install boto3==1.0.0 # Make sure Boto3 is no older than version 1.15.0 pip install boto3>=1.15.0 # Avoid versions of Boto3 newer than version 1.15.3 pip install boto3<=1.15.3 ``` To use Boto3, you must set up authentication credentials for your AWS account using the [IAM console](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey). ## Consider AWS Regions and endpoints An *endpoint* is a URL that's the entry point for a web service. Each endpoint is associated with a specific AWS Region. If you use a combination of the Amazon Q Business console, the AWS CLI, and the Amazon Q Business SDKs, pay attention to their default Regions. All Amazon Q Business components of a given application must be created in the same Region. Examples of a component include a retriever, an index, and a chat experience. To understand why this is important, see [Considerations for choosing an AWS Region](https://docs.aws.amazon.com/singlesignon/latest/userguide/get-started-prereqs-considerations.html) in the IAM Identity Center User Guide. For regions and endpoints supported by Amazon Q Business, see [Service quotas for Amazon Q Business](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/quotas-regions.html). ## Set up required permissions If you use Amazon Q Business through the AWS Management Console, basic required permissions are added on your behalf. To use Amazon Q Business as an IAM user on the AWS CLI, or AWS SDK, you must attach the following permissions to allow Amazon Q Business to create and manage resources on your behalf: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "QBusinessFullAccessPermissions", "Effect": "Allow", "Action": "qbusiness:*", "Resource": "*" } ] } ``` ------ If you're using Q Apps, add the following permissions: ``` "qapps:*" ``` If you're using Q Apps, add the following permissions: ``` "quicksight:*" ``` If you're using a customer managed key, add the following permissions: ``` "kms:DescribeKey" "kms:CreateGrant" ``` If you're using IAM Identity Center, add the following permissions: ``` "sso:CreateApplication", "sso:PutApplicationAuthenticationMethod", "sso:PutApplicationAccessScope", "sso:PutApplicationGrant", "sso:DeleteApplication", "organizations:DescribeOrganization", "sso-directory:DescribeGroup", "sso-directory:DescribeUser", "sso:DescribeApplication", "sso:DescribeInstance" ``` To assign user subscriptions to applications, you must include permissions to call the necessary user subscription-related APIs. The subscription-related APIs give permission to create, update, cancel, and view all user subscriptions for an application. You can assign user subscriptions through both the Amazon Q Business console and programmatically using the AWS CLI or AWS SDKs. **To allow Amazon Q to assign user subscriptions, use the following role policy:** ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "QBusinessSubscriptionPermissions", "Effect": "Allow", "Action": [ "qbusiness:UpdateSubscription", "qbusiness:CreateSubscription", "qbusiness:CancelSubscription", "qbusiness:ListSubscriptions" ], "Resource": [ "arn:aws:qbusiness:us-east-1:111122223333:application/application-id", "arn:aws:qbusiness:us-east-1:111122223333:application/application-id/subscription/subscription-id" ] }, { "Sid": "QBusinessServicePermissions", "Effect": "Allow", "Action": [ "user-subscriptions:UpdateClaim", "user-subscriptions:CreateClaim", "organizations:DescribeOrganization", "iam:CreateServiceLinkedRole", "sso-directory:DescribeGroup", "sso-directory:DescribeUser", "sso:DescribeApplication", "sso:DescribeInstance" ], "Resource": [ "*" ] } ] } ``` ------ ### Grant permission to create data sources with ACLs disabled By default, when Amazon Q administrators create data sources, ACLs are on. Some administrators may want to create data sources with ACLs disabled. You can grant them permission by attaching the IAM action `DisableAclOnDataSource` to their role or policy. With this permission, the administrator can create data sources with the ACL field disabled. If an administrator creates a data source with the ACL field set to enabled, they can't change the field to disabled. If they want to use a data source with ACLs disabled, they need to create a new data source. We don't recommend disabling ACLs in production environments. **Warning** When ACLs are disabled for a data source, all documents ingested by the data source become accessible to all end users of the Amazon Q Business application. You can check if data source connectors were created with ACLs disabled and whether Amazon Q administrators have the `DisableAclOnDataSource` IAM policy. To check ACLs on a data source, review `CreateDataSource` and `UpdateDataSource` event logs in CloudTrail. To check if administrators have been granted the `DisableAclOnDataSource`IAM action, review permissions in the IAM console. As a best practice, we recommend you use an explicit deny on the `DisableAclOnDataSource`IAM action and that you only grant the `DisableAclOnDataSource` permission when requested by Amazon Q administrators. **Note** This feature is only available for use with the following connectors: ServiceNow Online, Confluence, SharePoint, Jira, Google Drive, OneDrive, Salesforce, Zendesk, GitHub, MS Teams, and Slack. **Example An example policy using `qbusiness:DisableAclOnDataSource`** The following is an example policy showing how to use `qbusiness:DisableAclOnDataSource` **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "ExplicitDenyACLDisable", "Effect": "Deny", "Action": [ "qbusiness:DisableAclOnDataSource" ], "Resource": [ "*" ] } ] } ``` For a complete list of IAM roles for Amazon Q Business, see [IAM roles for Amazon Q Business](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html). # IAM roles for Amazon Q Business IAM roles When you create an application or a web experience with Amazon Q Business, or connect a data source to it, Amazon Q Business needs access to the required AWS resources. If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create the Amazon Q Business resource. When you call an API operation, you provide the Amazon Resource Name (ARN) role with the policy attached. If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role. The console displays roles that have the string **qbusiness** or **QBusiness** in the role name. To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*. The following topics provide details for the required policies. If you create IAM roles using the Amazon Q Business console, these policies are created on your behalf, unless otherwise noted. **Topics** + [ # IAM role for an Amazon Q Business application ](create-application-iam-role.md) + [ # IAM role for an Amazon Q Business web experience ](deploy-experience-iam-role.md) + [ # IAM role for Amazon Q Business data source connectors ](iam-roles-ds.md) + [ # IAM role for Amazon Q Business plugins ](plugin-iam-role.md) + [ # IAM roles for custom document enrichment in Amazon Q Business ](cde-iam-roles.md) + [ # IAM role for an Amazon Kendra retriever ](kendra-retriever-iam-role.md) # IAM role for an Amazon Q Business application Amazon Q Business application When you create an Amazon Q Business application, you must provide Amazon Q with an IAM role with permissions to write to an Amazon CloudWatch log and assign user subscriptions to applications. You must also provide a trust policy that allows Amazon Q to assume the role. The following are the policies that must be provided. **To allow Amazon Q to access a CloudWatch log and assign user subscriptions, use the following role policy:** ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AmazonQApplicationPutMetricDataPermission", "Effect": "Allow", "Action": [ "cloudwatch:PutMetricData" ], "Resource": "*", "Condition": { "StringEquals": { "cloudwatch:namespace": "AWS/QBusiness" } } }, { "Sid": "AmazonQApplicationDescribeLogGroupsPermission", "Effect": "Allow", "Action": [ "logs:DescribeLogGroups" ], "Resource": "*" }, { "Sid": "AmazonQApplicationCreateLogGroupPermission", "Effect": "Allow", "Action": [ "logs:CreateLogGroup" ], "Resource": [ "arn:aws:logs:us-east-1:111122223333:log-group:/aws/qbusiness/*" ] }, { "Sid": "AmazonQApplicationLogStreamPermission", "Effect": "Allow", "Action": [ "logs:DescribeLogStreams", "logs:CreateLogStream", "logs:PutLogEvents" ], "Resource": [ "arn:aws:logs:us-east-1:111122223333:log-group:/aws/qbusiness/*:log-stream:*" ] } ] } ``` ------ **To allow Amazon Q to assume a role, use the following trust policy:** ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AmazonQApplicationPermission", "Effect": "Allow", "Principal": { "Service": "qbusiness.amazonaws.com" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "aws:SourceAccount": "111122223333" }, "ArnLike": { "aws:SourceArn": "arn:aws:qbusiness:us-east-1:111122223333:application/*" } } } ] } ``` ------ **Amazon Q also supports using a service-linked role (`AWSServiceRoleForQBusiness`) for an Amazon Q application. The following is the service-linked role policy:** ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "QBusinessPutMetricDataPermission", "Effect": "Allow", "Action": [ "cloudwatch:PutMetricData" ], "Resource": "*", "Condition": { "StringEquals": { "cloudwatch:namespace": "AWS/QBusiness" } } }, { "Sid": "QBusinessCreateLogGroupPermission", "Effect": "Allow", "Action": [ "logs:CreateLogGroup" ], "Resource": [ "arn:aws:logs:*:*:log-group:/aws/qbusiness/*" ] }, { "Sid": "QBusinessDescribeLogGroupsPermission", "Effect": "Allow", "Action": [ "logs:DescribeLogGroups" ], "Resource": "*" }, { "Sid": "QBusinessLogStreamPermission", "Effect": "Allow", "Action": [ "logs:DescribeLogStreams", "logs:CreateLogStream", "logs:PutLogEvents" ], "Resource": [ "arn:aws:logs:*:*:log-group:/aws/qbusiness/*:log-stream:*" ] } ] } ``` ------ For more information on using service-linked roles for an Amazon Q application, see [Using service-linked roles](https://docs.aws.amazon.com/amazonq/latest/business-use-dg/using-service-linked-roles.html). # IAM role for an Amazon Q Business web experience Amazon Q Business web experience **Note** If you are using permissions for Amazon Q Apps created prior to July 10, 2024, you must update your role with the new [Amazon Q Apps](deploy-q-apps-iam-permissions.md) permissions for your users to have access to use the [permissions to view and specify approved data sources](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/deploy-q-apps-iam-permissions.html#deploy-data-source-iam-permissions) and other future features in Q Apps. To allow Amazon Q to invoke the API operations required to integrate your application environment, deploy your chat web experience, use an external IdP, and use Amazon Q Apps you must use the following IAM policies. **Topics** + [ # IAM role for an Amazon Q Business web experience using IAM Identity Center ](web-experience-iam-role-idc.md) + [ # IAM role for an Amazon Q Business web experience using IAM Federation ](web-experience-iam-role-iam.md) + [ # IAM permissions for using Amazon Q Apps ](deploy-q-apps-iam-permissions.md) # IAM role for an Amazon Q Business web experience using IAM Identity Center IAM Identity Center web experience **Important** This page only applies to Amazon Q Business web experiences connected to IAM Identity Center-integrated Amazon Q Business applications. **Policy history** + **Latest policy update:** — December 3, 2024 The following table list and describes the changes to this policy over time. | Change | Description | Date | | --- | --- | --- | | Amazon Q Business now supports deleting attachments | To enable delete attachments support on chats, modify your *Web experience IAM role* by adding the permission `qbusiness:DeleteAttachment`. The scoping for this new permission should be similar to other `qbusiness:` conversation permissions. With this change, users can remove attached files in conversations. | 2/27/2025 | | Amazon Q Business plugin actions support | To allow Amazon Q Business to list plugin actions and to allow end users to discover plugins in their web experience, modify the existing *Web experience IAM role* by adding the following permissions: `qbusiness:ListPluginActions`, `qbusiness:ListPluginTypeMetadata`, and `qbusiness:ListPluginTypeActions`. The scoping for this new permission should be similar to other `qbusiness:` conversation permissions. With this change, Amazon Q Business can list plugin actions and web experience users can discover plugins in their web experience. For more information, see [Prerequisites for configuring Amazon Q Business built-in plugins](basic-plugins-prereqs.md). | 12/03/2024 | | Amazon Quick plugin support | To allow the Quick plugin to include visuals from Amazon Quick, modify the existing *Web experience IAM role* to add permission for `quicksight:GenerateEmbedUrlForRegisteredUserWithIdentity`. With this change, web experience users can view visuals from Quick. For more information about the Quick plugin, see [Using the Quick plugin to get insights from structured data](quicksight-plugin.md). | 12/03/2024 | | Embedded visual content support | To enable extracting semantic meaning from embedded visual content, modify the existing *Web experience IAM role* by adding the permission `qbusiness:GetMedia`. The scoping for this new permission should be similar to other `qbusiness:` conversation permissions. With this change, if you enable content extraction for a data source, web experience users can ask questions and get answers related to the images. When an end user asks a question, Amazon Q Business retrieves relevant answers from the text and the images. Answers include the images and links for the documents that contain them. For more information, see [Extracting semantic meaning from embedded visual content with Amazon Q Business](extracting-meaning-from-images.md). | 12/01/2024 | | Recent files support | To enable recent files support on web experiences, modify the existing *Web experience IAM role* by adding the permission `qbusiness:ListAttachments`. The scoping for this new permission should be similar to other `qbusiness:` conversation permissions. With this change, users can find and reuse any recently attached files in new conversations without uploading the files again. Additionally, users can now drag and drop files they want to upload directly into any conversation inside their Amazon Q web experience. | 11/21/2024 | **Note** To find the IAM role ARN for your web experience you can go to ****Amazon Q Business** → **Applications** → *choose your application* **Name** → **Web experience settings**** in the Amazon Q Business console. The following section lists the IAM policies required to allow you to invoke the API operations required to integrate your application environment with IAM Identity Center. To allow an Amazon Q Business web experience to invoke the API operations required to integrate your application environment and deploy your web experience with an IAM Identity Center instance, use the following policy: **Note** To make use of the Clickable URL feature, add the following permissions to the IAM role for your Amazon Q web experience. ``` { "Sid": "QBusinessGetDocumentContentPermission", "Effect": "Allow", "Action": ["qbusiness:GetDocumentContent"], "Resource": [ "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}", "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/*" ] } ``` To allow Amazon Q to assume this role, use the following trust policy: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "QBusinessTrustPolicy", "Effect": "Allow", "Principal": { "Service": "application.qbusiness.amazonaws.com" }, "Action": [ "sts:AssumeRole", "sts:SetContext" ], "Condition": { "StringEquals": { "aws:SourceAccount": "111122223333" }, "ArnEquals": { "aws:SourceArn": "arn:aws:qbusiness:us-east-1:111122223333:application/application-id" } } } ] } ``` ------ # IAM role for an Amazon Q Business web experience using IAM Federation IAM Federation web experience **Important** This page only applies to Amazon Q Business web experiences connected to IAM Federated Amazon Q Business applications. **Policy history** + **Latest policy update:** — December 3, 2024 The following table list and describes the changes to this policy over time. | Change | Description | Date | | --- | --- | --- | | Amazon Q Business now supports deleting attachments | To enable delete attachments support on chats, modify your *Web experience IAM role* by adding the permission `qbusiness:DeleteAttachment`. The scoping for this new permission should be similar to other `qbusiness:` conversation permissions. With this change, users can remove attached files in conversations. | 2/27/2025 | | Amazon Q Business plugin actions support | To allow Amazon Q Business to list plugin actions and to allow end users to discover plugins in their web experience, modify the existing *Web experience IAM role* by adding the following permissions: `qbusiness:ListPluginActions`, `qbusiness:ListPluginTypeMetadata`, and `qbusiness:ListPluginTypeActions`. The scoping for this new permission should be similar to other `qbusiness:` conversation permissions. With this change, Amazon Q Business can list plugin actions and web experience users can discover plugins in their web experience. For more information, see [Prerequisites for configuring Amazon Q Business built-in plugins](basic-plugins-prereqs.md). | 12/03/2024 | | Embedded visual content support | To enable extracting semantic meaning from embedded visual content, modify the existing *Web experience IAM role* by adding the permission `qbusiness:GetMedia`. The scoping for this new permission should be similar to other `qbusiness:` conversation permissions. With this change, if you enable content extraction for a data source, web experience users can ask questions and get answers related to the images. When an end user asks a question, Amazon Q Business retrieves relevant answers from the text and the images. Answers include the images and links for the documents that contain them. For more information, see [Extracting semantic meaning from embedded visual content with Amazon Q Business](extracting-meaning-from-images.md). | 12/01/2024 | | Recent files support | To enable recent files support on web experiences, modify the existing *Web experience IAM role* by adding the permission `qbusiness:ListAttachments`. The scoping for this new permission should be similar to other `qbusiness:` conversation permissions. With this change, users can find and reuse any recently attached files in new conversations without uploading the files again. Additionally, users can now drag and drop files they want to upload directly into any conversation inside their Amazon Q web experience. | 11/21/2024 | **Note** To find the IAM role ARN for your web experience you can go to ****Amazon Q Business** → **Applications** → *choose your application* **Name** → **Web experience settings**** in the Amazon Q Business console. The following IAM policies allow you to invoke the API operations required for an application environment using Identity Federation through IAM (IAM Federation) to manage user access or deploy a web experience using an external IdP. **Note** You must create and update an IAM policy for your Amazon Q Business application (both console and API) before you begin creating it. Amazon Q Business doesn't auto-create IAM roles for your IAM Federation application if you use the console. To allow an Amazon Q Business web experience to invoke the API operations required to integrate your application environment and deploy your web experience with an AWS Identity and Access Management instance, use the following policy: **Note** To make use of the Clickable URL feature, add the following permissions to the IAM role for your Amazon Q web experience. ``` { "Sid": "QBusinessGetDocumentContentPermission", "Effect": "Allow", "Action": ["qbusiness:GetDocumentContent"], "Resource": [ "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}", "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/*" ] } ``` ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "QBusinessConversationPermissions", "Effect": "Allow", "Action": [ "qbusiness:Chat", "qbusiness:ChatSync", "qbusiness:ListMessages", "qbusiness:ListConversations", "qbusiness:PutFeedback", "qbusiness:DeleteConversation", "qbusiness:GetWebExperience", "qbusiness:GetApplication", "qbusiness:ListPlugins", "qbusiness:GetChatControlsConfiguration", "qbusiness:ListRetrievers", "qbusiness:ListPluginActions", "qbusiness:ListAttachments", "qbusiness:GetMedia", "qbusiness:DeleteAttachment" ], "Resource": "arn:aws:qbusiness:us-east-1:111122223333:application/application-id" }, { "Sid": "QBusinessPluginDiscoveryPermissions", "Effect": "Allow", "Action": [ "qbusiness:ListPluginTypeMetadata", "qbusiness:ListPluginTypeActions" ], "Resource": "*" }, { "Sid": "QBusinessRetrieverPermission", "Effect": "Allow", "Action": [ "qbusiness:GetRetriever" ], "Resource": [ "arn:aws:qbusiness:us-east-1:111122223333:application/application-id", "arn:aws:qbusiness:us-east-1:111122223333:application/application-id/retriever/*" ] }, { "Sid": "QBusinessAutoSubscriptionPermission", "Effect": "Allow", "Action": [ "user-subscriptions:CreateClaim" ], "Condition": { "Bool": { "user-subscriptions:CreateForSelf": "true" }, "StringEquals": { "aws:CalledViaLast": "qbusiness.amazonaws.com" } }, "Resource": [ "*" ] }, { "Sid": "QBusinessKMSDecryptPermissions", "Effect": "Allow", "Action": [ "kms:Decrypt" ], "Resource": [ "arn:aws:kms:us-east-1:111122223333:key/key-id" ], "Condition": { "StringLike": { "kms:ViaService": [ "qbusiness.us-east-1.amazonaws.com", "qapps.us-east-1.amazonaws.com" ] } } }, { "Sid": "QAppsResourceAgnosticPermissions", "Effect": "Allow", "Action": [ "qapps:CreateQApp", "qapps:PredictQApp", "qapps:PredictProblemStatementFromConversation", "qapps:PredictQAppFromProblemStatement", "qapps:ListQApps", "qapps:ListLibraryItems", "qapps:CreateSubscriptionToken" ], "Resource": "arn:aws:qbusiness:us-east-1:111122223333:application/application-id" }, { "Sid": "QAppsAppUniversalPermissions", "Effect": "Allow", "Action": [ "qapps:DisassociateQAppFromUser" ], "Resource": "arn:aws:qapps:us-east-1:111122223333:application/application-id/qapp/*" }, { "Sid": "QAppsAppOwnerPermissions", "Effect": "Allow", "Action": [ "qapps:GetQApp", "qapps:CopyQApp", "qapps:UpdateQApp", "qapps:DeleteQApp", "qapps:ImportDocument", "qapps:CreateLibraryItem", "qapps:UpdateLibraryItem", "qapps:StartQAppSession" ], "Resource": "arn:aws:qapps:us-east-1:111122223333:application/application-id/qapp/*", "Condition": { "StringEqualsIgnoreCase": { "qapps:UserIsAppOwner": "true" } } }, { "Sid": "QAppsPublishedAppPermissions", "Effect": "Allow", "Action": [ "qapps:GetQApp", "qapps:CopyQApp", "qapps:AssociateQAppWithUser", "qapps:GetLibraryItem", "qapps:CreateLibraryItemReview", "qapps:AssociateLibraryItemReview", "qapps:DisassociateLibraryItemReview", "qapps:StartQAppSession" ], "Resource": "arn:aws:qapps:us-east-1:111122223333:application/application-id/qapp/*", "Condition": { "StringEqualsIgnoreCase": { "qapps:AppIsPublished": "true" } } }, { "Sid": "QAppsAppSessionModeratorPermissions", "Effect": "Allow", "Action": [ "qapps:ImportDocument", "qapps:GetQAppSession", "qapps:GetQAppSessionMetadata", "qapps:UpdateQAppSession", "qapps:UpdateQAppSessionMetadata", "qapps:StopQAppSession" ], "Resource": "arn:aws:qapps:us-east-1:111122223333:application/application-id/qapp/*/session/*", "Condition": { "StringEqualsIgnoreCase": { "qapps:UserIsSessionModerator": "true" } } }, { "Sid": "QAppsSharedAppSessionPermissions", "Effect": "Allow", "Action": [ "qapps:ImportDocument", "qapps:GetQAppSession", "qapps:GetQAppSessionMetadata", "qapps:UpdateQAppSession" ], "Resource": "arn:aws:qapps:us-east-1:111122223333:application/application-id/qapp/*/session/*", "Condition": { "StringEqualsIgnoreCase": { "qapps:SessionIsShared": "true" } } } ] } ``` ------ **To allow Amazon Q to assume this role for a web experience using SAML-compliant identity provider for user management, use the following trust policy:** ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Action": "sts:AssumeRoleWithSAML", "Sid": "SAMLAssumeRoleAccess", "Effect": "Allow", "Condition": { "StringEquals": { "SAML:aud": "https://q-web-experience-domain/saml" } }, "Principal": { "Federated": "arn:aws:iam::111122223333:saml-provider/[[saml_provider]]" } }, { "Action": "sts:TagSession", "Sid": "SAMLTagSessionAccess", "Effect": "Allow", "Condition": { "StringLike": { "aws:RequestTag/Email": "*" } }, "Principal": { "Federated": "arn:aws:iam::111122223333:saml-provider/[[saml_provider]]" } } ] } ``` ------ **To allow Amazon Q to assume this role for a web experience using an OIDC-compliant identity provider for user management, use the following trust policy:** **To allow an Amazon Q Business web experience to access AWS KMS to decrypt an OIDC client secret stored in Secrets Manager for an OIDC-based identity provider:** ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowsAmazonQToGetSecret", "Effect": "Allow", "Action": [ "secretsmanager:GetSecretValue" ], "Resource": [ "arn:aws:secretsmanager:us-east-1:111122223333:secret:secret-id" ] }, { "Sid": "AllowsAmazonQToDecryptSecret", "Effect": "Allow", "Action": [ "kms:Decrypt" ], "Resource": [ "arn:aws:kms:us-east-1:111122223333:key/key-id" ], "Condition": { "StringLike": { "kms:ViaService": [ "secretsmanager.*.amazonaws.com" ] } } } ] } ``` ------ **To allow Amazon Q to assume the role to decrypt an OIDC client secret stored in Secrets Manager, use the following trust policy:** ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowsAmazonQToAssumeRoleForServicePrincipal", "Effect": "Allow", "Principal": { "Service": "application.qbusiness.amazonaws.com" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "aws:SourceAccount": "111122223333" }, "ArnLike": { "aws:SourceArn": "arn:aws:qbusiness:us-east-1:111122223333:application/application-id" } } } ] } ``` ------ # IAM permissions for using Amazon Q Apps Amazon Q Apps If the users of your deployed web experience want to create lightweight, purpose-built Amazon Q Apps within your broader Amazon Q Business application environment, you must include the following policy permissions. **Note** This Amazon Q Apps IAM policy released on July 10, 2024 supports the ability for users to view and specify approved *data sources* at the card-level and use other future features. To use these features, you must update all roles for Amazon Q Apps that have been created prior to this date with this new policy. | Change | Description | Date | | --- | --- | --- | | Deprecated some IAM actions related to file upload | The `qapps:ImportDocumentToQApp`, `qapps:ImportDocumentToQAppSession`, and `qapps:CreatePresignedUrl` IAM actions are deprecated. The `qapps:ImportDocument` action now serves as the single file upload action. | 05/22/2025 | | Added Permission to ` CreatePresignedUrl ` | This new API allows users to leverage the improved file limits in Amazon Q Apps. You can now upload files with size up to 10MB (per file card). | 11/22/2024 | | Added Permissions to ` DescribeQAppPermissions ` and `UpdateQAppPermissions` | These new APIs allows users [privately share Amazon Q Apps](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/qapps-private-sharing.html) to leverage the improved file limits in Amazon Q Apps. You can now upload files with size up to 10MB (per file card). | 11/22/2024 | | Added permissions related to management of persistent sessions. | These new APIs allows users to start, manage and terminate long running collaborative [data collection sessions](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/q-apps-forms.html) to leverage the improved file limits in Amazon Q Apps. You can now upload files with size up to 10MB (per file card). | 11/22/2024 | **Topics** + [ ## Capabilities available with Amazon Q Apps ](#q-apps-actions) + [ ## IAM permissions for users to view and specify approved data sources in Amazon Q Apps ](#deploy-data-source-iam-permissions) **If you want to use Amazon Q Apps, your web experience IAM role needs the following additional permissions:** ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "QAppsResourceAgnosticPermissions", "Effect": "Allow", "Action": [ "qapps:CreateQApp", "qapps:PredictQApp", "qapps:PredictProblemStatementFromConversation", "qapps:PredictQAppFromProblemStatement", "qapps:ListQApps", "qapps:ListLibraryItems", "qapps:CreateSubscriptionToken" ], "Resource": "arn:aws:qbusiness:us-east-1:111122223333:application/application-id" }, { "Sid": "QAppsAppUniversalPermissions", "Effect": "Allow", "Action": [ "qapps:DisassociateQAppFromUser" ], "Resource": "arn:aws:qapps:us-east-1:111122223333:application/application-id/qapp/*" }, { "Sid": "QAppsAppOwnerPermissions", "Effect": "Allow", "Action": [ "qapps:GetQApp", "qapps:CopyQApp", "qapps:UpdateQApp", "qapps:DeleteQApp", "qapps:ImportDocument", "qapps:CreateLibraryItem", "qapps:UpdateLibraryItem", "qapps:StartQAppSession", "qapps:DescribeQAppPermissions", "qapps:UpdateQAppPermissions" ], "Resource": "arn:aws:qapps:us-east-1:111122223333:application/application-id/qapp/*", "Condition": { "StringEqualsIgnoreCase": { "qapps:UserIsAppOwner": "true" } } }, { "Sid": "QAppsPublishedAppPermissions", "Effect": "Allow", "Action": [ "qapps:GetQApp", "qapps:CopyQApp", "qapps:AssociateQAppWithUser", "qapps:GetLibraryItem", "qapps:CreateLibraryItemReview", "qapps:AssociateLibraryItemReview", "qapps:DisassociateLibraryItemReview", "qapps:StartQAppSession", "qapps:DescribeQAppPermissions" ], "Resource": "arn:aws:qapps:us-east-1:111122223333:application/application-id/qapp/*", "Condition": { "StringEqualsIgnoreCase": { "qapps:AppIsPublished": "true" } } }, { "Sid": "QAppsAppSessionModeratorPermissions", "Effect": "Allow", "Action": [ "qapps:ImportDocument", "qapps:GetQAppSession", "qapps:GetQAppSessionMetadata", "qapps:UpdateQAppSession", "qapps:UpdateQAppSessionMetadata", "qapps:StopQAppSession", "qapps:ListQAppSessionData", "qapps:ExportQAppSessionData" ], "Resource": "arn:aws:qapps:us-east-1:111122223333:application/application-id/qapp/*/session/*", "Condition": { "StringEqualsIgnoreCase": { "qapps:UserIsSessionModerator": "true" } } }, { "Sid": "QAppsSharedAppSessionPermissions", "Effect": "Allow", "Action": [ "qapps:ImportDocument", "qapps:GetQAppSession", "qapps:GetQAppSessionMetadata", "qapps:UpdateQAppSession", "qapps:ListQAppSessionData" ], "Resource": "arn:aws:qapps:us-east-1:111122223333:application/application-id/qapp/*/session/*", "Condition": { "StringEqualsIgnoreCase": { "qapps:SessionIsShared": "true" } } } ] } ``` ------ ## Capabilities available with Amazon Q Apps Capabilities with Q Apps The Amazon Q Apps IAM policy allows your web experience users permissions to do the following: + **Amazon Q Apps capabilities:** + Create a Q App ([API](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_qapps_CreateQApp.html)) + Get the status and other information on a Q App ([API](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_qapps_GetQApp.html)) + Update a Q App ([API](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_qapps_UpdateQApp.html)) + List all created Q Apps ([API](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_qapps_ListQApps.html)) + Delete a Q App ([API](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_qapps_DeleteQApp.html)) + Start a Q App run (session) ([API](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_qapps_StartQAppSession.html)) + Stop a Q App run (session) ([API](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_qapps_StopQAppSession.html)) + Upload files to a Q App run (session) ([API](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_qapps_ImportDocument.html)) + Converts a conversation into a (*text string*) problem statement ([API](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_qapps_PredictQApp.html)) + Convert a problem statement into a proposed Q App ([API](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_qapps_PredictQApp.html)) + **Amazon Q Apps library capabilities:** + Publish a Q App by adding items to your Q Apps library ([API](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_qapps_CreateLibraryItem.html)) + Get the status and other information on a Q App (item) in your Q Apps library ([API](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_qapps_GetLibraryItem.html)) + Update a published Q App (item) in your Q Apps library ([API](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_qapps_UpdateLibraryItem.html)) + List all Q Apps (items) from your Q Apps library ([API](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_qapps_ListLibraryItems.html)) + Delete a Q App (item) from your Q Apps library ([API](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_qapps_DeleteLibraryItem.html)) + Like (rate) a Q App item from your Q Apps library ([API](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_qapps_AssociateLibraryItemReview.html)) ## IAM permissions for users to view and specify approved data sources in Amazon Q Apps Data sources **(Optional) You must add the following permissions to the Amazon Q Apps policy to allow Q Apps users to view and specify approved data sources** in their app. **Note** If you are using permissions for Amazon Q Apps created prior to July 10, 2024, you must update your role with the new [Amazon Q Apps](#deploy-q-apps-iam-permissions) permissions for your users to have access to use the [permissions to view and specify approved data sources](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/deploy-q-apps-iam-permissions.html#deploy-data-source-iam-permissions) and other future features in Q Apps. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "QBusinessIndexPermission", "Effect": "Allow", "Action": [ "qbusiness:ListIndices" ], "Resource": "arn:aws:qbusiness:us-east-1:111122223333:application/application-id" }, { "Sid": "QBusinessDataSourcePermission", "Effect": "Allow", "Action": [ "qbusiness:ListDataSources" ], "Resource": [ "arn:aws:qbusiness:us-east-1:111122223333:application/application-id", "arn:aws:qbusiness:us-east-1:111122223333:application/application-id/index/*" ] } ] } ``` ------ **Note** If any of these permissions are removed, then you run the risk of your web experience users not being able to create and run their own Q Apps properly. # IAM role for Amazon Q Business data source connectors Data source connectors You can use either the Amazon Q Business console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API operation to connect your data source. However, you must first provide Amazon Q Business with an IAM role that has permissions to access the data source resources. If you use the console, you can either create an IAM role when you connect your data source to Amazon Q Business or use an existing role. If you use the `CreateDataSource` API operation, you must provide the Amazon Resource Name (ARN) of an existing IAM role. The specific permissions required depend on the data source. At a minimum, your IAM role must include the following: + Permission to access the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_BatchPutDocument.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_BatchPutDocument.html) and [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_BatchDeleteDocument.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_BatchDeleteDocument.html) API operations in order to ingest documents. + Permission to access the User Store APIs needed to ingest access control and identity information from documents. **Topics** + [ ## IAM role for Amazon Q Business data source connectors ](#iam-roles-ds-general) + [ ## IAM role for Amazon S3 data sources ](#create-s3-datasource-iam-role) ## IAM role for Amazon Q Business data source connectors When you use an Amazon Q Business data source, you require the following permissions, depending on your use case. **To allow Amazon Q Business to connect to your data source, use the following least-permissions role policy:** **Note** This policy assumes your data source doesn't use any authentication. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowsAmazonQToIngestDocuments", "Effect": "Allow", "Action": [ "qbusiness:BatchPutDocument", "qbusiness:BatchDeleteDocument" ], "Resource": [ "arn:aws:qbusiness:us-east-1:111122223333:application/application-id", "arn:aws:qbusiness:us-east-1:111122223333:application/application-id/index/index-id" ] }, { "Sid": "AllowsAmazonQToIngestPrincipalMapping", "Effect": "Allow", "Action": [ "qbusiness:PutGroup", "qbusiness:CreateUser", "qbusiness:DeleteGroup", "qbusiness:UpdateUser", "qbusiness:ListGroups" ], "Resource": [ "arn:aws:qbusiness:us-east-1:111122223333:application/application-id", "arn:aws:qbusiness:us-east-1:111122223333:application/application-id/index/index-id", "arn:aws:qbusiness:us-east-1:111122223333:application/application-id/index/index-id/data-source/*" ] } ] } ``` ------ **To allow Amazon Q Business to assume a role, you must also use the following trust policy:** ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowsAmazonQToAssumeRoleForServicePrincipal", "Effect": "Allow", "Principal": { "Service": "qbusiness.amazonaws.com" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "aws:SourceAccount": "111122223333" }, "ArnLike": { "aws:SourceArn": "arn:aws:qbusiness:us-east-1:111122223333:application/application-id" } } } ] } ``` ------ **If your data source uses authentication, you must add the following policy to your IAM role to allow Amazon Q Business to access your AWS Secrets Manager secret:** ``` { "Sid": "AllowsAmazonQToGetSecret", "Effect": "Allow", "Action": [ "secretsmanager:GetSecretValue" ], "Resource": [ "arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]" ] } ``` **If you are using an Amazon VPC, you must add the following VPC access permissions to your policy:** ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowsAmazonQToCreateAndDeleteNI", "Effect": "Allow", "Action": [ "ec2:CreateNetworkInterface", "ec2:DeleteNetworkInterface" ], "Resource": [ "arn:aws:ec2:us-east-1:111122223333:subnet/[[subnet_ids]]", "arn:aws:ec2:us-east-1:111122223333:security-group/[[security_group]]" ] }, { "Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag", "Effect": "Allow", "Action": [ "ec2:CreateNetworkInterface", "ec2:DeleteNetworkInterface" ], "Resource": "arn:aws:ec2:us-east-1:111122223333:network-interface/*", "Condition": { "StringLike": { "aws:RequestTag/AMAZON_Q": "qbusiness_111122223333_application-id_*" }, "ForAllValues:StringEquals": { "aws:TagKeys": [ "AMAZON_Q" ] } } }, { "Sid": "AllowsAmazonQToCreateTags", "Effect": "Allow", "Action": [ "ec2:CreateTags" ], "Resource": "arn:aws:ec2:us-east-1:111122223333:network-interface/*", "Condition": { "StringEquals": { "ec2:CreateAction": "CreateNetworkInterface" } } }, { "Sid": "AllowsAmazonQToCreateNetworkInterfacePermission", "Effect": "Allow", "Action": [ "ec2:CreateNetworkInterfacePermission" ], "Resource": "arn:aws:ec2:us-east-1:111122223333:network-interface/*", "Condition": { "StringLike": { "aws:ResourceTag/AMAZON_Q": "qbusiness_111122223333_application-id_*" } } }, { "Sid": "AllowsAmazonQToDescribeResourcesForVPC", "Effect": "Allow", "Action": [ "ec2:DescribeNetworkInterfaces", "ec2:DescribeAvailabilityZones", "ec2:DescribeNetworkInterfaceAttribute", "ec2:DescribeVpcs", "ec2:DescribeRegions", "ec2:DescribeNetworkInterfacePermissions", "ec2:DescribeSubnets" ], "Resource": "*" } ] } ``` ------ **If your Secrets Manager secret is encrypted, you must add permissions for AWS KMS key to decrypt the username and password secret stored by Secrets Manager:** ``` { "Effect": "Allow", "Action": [ "kms:Decrypt" ], "Resource": [ "arn:aws:kms:your-region:your-account-id:key/key-id" ], "Condition": { "StringLike": { "kms:ViaService": [ "s3.*.amazonaws.com" ] } } } ``` **If your Amazon Q Business data source connector needs access to an object stored in an Amazon S3 bucket (such as an SSL certificate), you must add the following permissions to your IAM role: ** **Note** Check that the file path to the object in your Amazon S3 bucket is of the following format: *s3://BucketName/FolderName/FileName.extension*. ``` { "Sid": "AllowsAmazonQToGetS3Objects", "Action": [ "s3:GetObject" ], "Resource": [ "arn:aws:s3:::{{input_bucket_name}}/*" ], "Effect": "Allow", "Condition": { "StringEquals": { "aws:ResourceAccount": "{{account_id}}" } } } ``` ## IAM role for Amazon S3 data sources IAM role for Amazon S3 data source If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q Business resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached. If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role while creating your data source. **Note** To learn how to create an IAM role, see [Create a role to delegate permissions to an AWS service](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html). When you use an Amazon S3 bucket as a data source, you must provide a role that has permissions to: + Access your Amazon S3 bucket. + Permission to access the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_BatchPutDocument.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_BatchPutDocument.html) and [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_BatchDeleteDocument.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_BatchDeleteDocument.html) API operations in order to ingest documents. + Access the Principal Store APIs needed to ingest access control and identity information from documents. **To allow Amazon Q to use an Amazon S3 bucket as a data source, use the following role policy:** ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowsAmazonQToGetObjectfromS3", "Action": [ "s3:GetObject" ], "Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket/*" ], "Effect": "Allow", "Condition": { "StringEquals": { "aws:ResourceAccount": "111122223333" } } }, { "Sid": "AllowsAmazonQToListS3Buckets", "Action": [ "s3:ListBucket" ], "Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket" ], "Effect": "Allow", "Condition": { "StringEquals": { "aws:ResourceAccount": "111122223333" } } }, { "Sid": "AllowsAmazonQToIngestDocuments", "Effect": "Allow", "Action": [ "qbusiness:BatchPutDocument", "qbusiness:BatchDeleteDocument" ], "Resource": [ "arn:aws:qbusiness:us-east-1:111122223333:application/application-id", "arn:aws:qbusiness:us-east-1:111122223333:application/application-id/index/index-id" ] }, { "Sid": "AllowsAmazonQToCallPrincipalMappingAPIs", "Effect": "Allow", "Action": [ "qbusiness:PutGroup", "qbusiness:CreateUser", "qbusiness:DeleteGroup", "qbusiness:UpdateUser", "qbusiness:ListGroups" ], "Resource": [ "arn:aws:qbusiness:us-east-1:111122223333:application/application-id", "arn:aws:qbusiness:us-east-1:111122223333:application/application-id/index/index-id", "arn:aws:qbusiness:us-east-1:111122223333:application/application-id/index/index-id/data-source/*" ] } ] } ``` ------ **If the documents in the Amazon S3 bucket are encrypted, you must provide the following permissions to use the AWS KMS key to decrypt the documents:** ``` { "Sid": "AllowsAmazonQToDecryptSecret", "Effect": "Allow", "Action": [ "kms:Decrypt" ], "Resource": [ "arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]" ], "Condition": { "StringLike": { "kms:ViaService": [ "secretsmanager.*.amazonaws.com" ] } } } ``` **If you are using an Amazon VPC, you must add the following VPC access permissions to your policy:** ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowsAmazonQToGetObjectfromS3", "Action": [ "s3:GetObject" ], "Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket/*" ], "Effect": "Allow", "Condition": { "StringEquals": { "aws:ResourceAccount": "111122223333" } } }, { "Sid": "AllowsAmazonQToListS3Buckets", "Action": [ "s3:ListBucket" ], "Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket" ], "Effect": "Allow", "Condition": { "StringEquals": { "aws:ResourceAccount": "111122223333" } } }, { "Sid": "AllowsAmazonQToIngestDocuments", "Effect": "Allow", "Action": [ "qbusiness:BatchPutDocument", "qbusiness:BatchDeleteDocument" ], "Resource": [ "arn:aws:qbusiness:us-east-1:111122223333:application/application-id", "arn:aws:qbusiness:us-east-1:111122223333:application/application-id/index/index-id" ] }, { "Sid": "AllowsAmazonQToCallPrincipalMappingAPIs", "Effect": "Allow", "Action": [ "qbusiness:PutGroup", "qbusiness:CreateUser", "qbusiness:DeleteGroup", "qbusiness:UpdateUser", "qbusiness:ListGroups" ], "Resource": [ "arn:aws:qbusiness:us-east-1:111122223333:application/application-id", "arn:aws:qbusiness:us-east-1:111122223333:application/application-id/index/index-id", "arn:aws:qbusiness:us-east-1:111122223333:application/application-id/index/index-id/data-source/*" ] }, { "Sid": "AllowsAmazonQToCreateAndDeleteENI", "Effect": "Allow", "Action": [ "ec2:CreateNetworkInterface", "ec2:DeleteNetworkInterface" ], "Resource": [ "arn:aws:ec2:us-east-1:111122223333:subnet/[[subnet_ids]]", "arn:aws:ec2:us-east-1:111122223333:security-group/[[security_group]]" ] }, { "Sid": "AllowsAmazonQToCreateDeleteENI", "Effect": "Allow", "Action": [ "ec2:CreateNetworkInterface", "ec2:DeleteNetworkInterface" ], "Resource": "arn:aws:ec2:us-east-1:111122223333:network-interface/*", "Condition": { "StringLike": { "aws:RequestTag/AMAZON_Q": "qbusiness_111122223333_application-id_*" }, "ForAllValues:StringEquals": { "aws:TagKeys": [ "AMAZON_Q" ] } } }, { "Sid": "AllowsAmazonQToCreateTags", "Effect": "Allow", "Action": [ "ec2:CreateTags" ], "Resource": "arn:aws:ec2:us-east-1:111122223333:network-interface/*", "Condition": { "StringEquals": { "ec2:CreateAction": "CreateNetworkInterface" } } }, { "Sid": "AllowsAmazonQToCreateNetworkInterfacePermission", "Effect": "Allow", "Action": [ "ec2:CreateNetworkInterfacePermission" ], "Resource": "arn:aws:ec2:us-east-1:111122223333:network-interface/*", "Condition": { "StringLike": { "aws:ResourceTag/AMAZON_Q": "qbusiness_111122223333_application-id_*" } } }, { "Sid": "AllowsAmazonQToConnectToVPC", "Effect": "Allow", "Action": [ "ec2:DescribeNetworkInterfaces", "ec2:DescribeAvailabilityZones", "ec2:DescribeNetworkInterfaceAttribute", "ec2:DescribeVpcs", "ec2:DescribeRegions", "ec2:DescribeNetworkInterfacePermissions", "ec2:DescribeSubnets" ], "Resource": "*" } ] } ``` ------ **To allow Amazon Q to assume a role, use the following trust policy:** ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowsAmazonQToAssumeRoleForServicePrincipal", "Effect": "Allow", "Principal": { "Service": "qbusiness.amazonaws.com" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "aws:SourceAccount": "111122223333" }, "ArnLike": { "aws:SourceArn": "arn:aws:qbusiness:us-east-1:111122223333:application/application-id" } } } ] } ``` ------ # IAM role for Amazon Q Business plugins Plugins To successfully connect Amazon Q Business to a plugin, you need to give Amazon Q Business the following permissions using a service access role: + Permission to access your Secrets Manager secret to get the credentials you use to log in to the third party service instance you are creating a plugin for. + **(Optional)** Permission to access the customer managed AWS KMS key used to encrypt the content of your Secrets Manager secret. Amazon Q Business assumes this role to access your third party service instance credentials. If you use the console and choose to create a new IAM role, Amazon Q creates the IAM role for you. If you use the console and choose to use an existing secret, or you use the API, make sure your secret contains the following permissions. **Important** If you're changing response settings for an Amazon Q Business application created and deployed before 16 April, 2024, you need to update your web experience service role. For information on service role permissions needed, see [IAM role for an Amazon Q Business web experience](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#deploy-experience-iam-role). For information on how to update your web experience service role, see [Updating a web experience](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-exp-actions.html#update-web-experience). The following is the service access IAM role required: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowQBusinessToGetSecretValue", "Effect": "Allow", "Action": [ "secretsmanager:GetSecretValue" ], "Resource": [ "arn:aws:secretsmanager:us-east-1:111122223333:secret:[[secret_id]]" ] } ] } ``` ------ **To allow Amazon Q Business to assume a role, use the following trust policy:** ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "QBusinessApplicationTrustPolicy", "Effect": "Allow", "Principal": { "Service": "qbusiness.amazonaws.com" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "aws:SourceAccount": "111122223333" }, "ArnLike": { "aws:SourceArn": "arn:aws:qbusiness:us-east-1:111122223333:application/application-id" } } } ] } ``` ------ # IAM roles for custom document enrichment in Amazon Q Business Custom document enrichment Custom document enrichment (CDE) is an Amazon Q Business feature that you can use to manipulate your document content and document attributes. When you use the Lambda functions for CDE, you need an IAM role for the following: + A role for `PreExtractionHookConfiguration` with permissions to run `PreExtractionHookConfiguration` and to access the Amazon S3 bucket when you use `PreExtractionHookConfiguration`. + A role for `PostExtractionHookConfiguration` with permissions to run `PreExtractionHookConfiguration` and to access the Amazon S3 bucket when you use `PostExtractionHookConfiguration`. **Important** IAM roles for Custom Document Enrichmmnt (CDE) Lambda functions should belong to the same account as the account using [BatchPutDocument](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_BatchPutDocument.html) API operation or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation to configure CDE. Both AWS Identity and Access Management (IAM) roles must have the permissions to: + Run `PreExtractionHookConfiguration` and/or `PostExtractionHookConfiguration`. To apply advanced alterations of your document metadata and content during the ingestion process, configure a Lambda function for `PreExtractionHookConfiguration` and/or `PostExtractionHookConfiguration`. + (Optional) If you choose to activate Server Side Encryption for your Amazon S3 bucket, you must provide permissions to use the AWS KMS key customer to encrypt and decrypt the objects stored in your Amazon S3 bucket. **A role policy to allow Amazon Q to run `PreExtractionHookConfiguration` with encryption for your Amazon S3 bucket.** ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Action": [ "s3:GetObject", "s3:PutObject" ], "Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket", "arn:aws:s3:::amzn-s3-demo-bucket/*" ], "Effect": "Allow", "Sid": "S3GetObjectPermissions" }, { "Action": [ "s3:ListBucket" ], "Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket" ], "Effect": "Allow", "Sid": "S3ListBucketPermissions" }, { "Action": [ "kms:Decrypt", "kms:GenerateDataKey" ], "Resource": [ "arn:aws:kms:us-east-1:111122223333:key/key-id" ], "Effect": "Allow", "Sid": "KMSPermissions" }, { "Action": [ "lambda:InvokeFunction" ], "Resource": "arn:aws:lambda:us-east-1:111122223333:function:pre-extraction-lambda-function", "Effect": "Allow", "Sid": "LambdaPermissions" } ] } ``` ------ **An role policy to allow Amazon Q to run `PreExtractionHookConfiguration` without encryption.** ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Action": [ "s3:GetObject", "s3:PutObject" ], "Resource": [ "arn:aws:s3:::bucket-name", "arn:aws:s3:::bucket-name/*" ], "Effect": "Allow", "Sid": "S3GetObjectPermissions" }, { "Action": [ "s3:ListBucket" ], "Resource": [ "arn:aws:s3:::bucket-name" ], "Effect": "Allow", "Sid": "S3ListBucketPermissions" }, { "Action": [ "lambda:InvokeFunction" ], "Resource": "arn:aws:lambda:us-east-1:111122223333:function:pre-extraction-lambda-function", "Effect": "Allow", "Sid": "LambdaPermissions" } ] } ``` ------ **A role policy to allow Amazon Q to run `PostExtractionHookConfiguration` with encryption for your Amazon S3 bucket.** ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Action": [ "s3:GetObject", "s3:PutObject" ], "Resource": [ "arn:aws:s3:::bucket-name", "arn:aws:s3:::bucket-name/*" ], "Effect": "Allow", "Sid": "S3GetObjectPermissions" }, { "Action": [ "s3:ListBucket" ], "Resource": [ "arn:aws:s3:::bucket-name" ], "Effect": "Allow", "Sid": "S3ListBucketPermissions" }, { "Action": [ "kms:Decrypt", "kms:GenerateDataKey" ], "Resource": [ "arn:aws:kms:us-east-1:111122223333:key/key-id" ], "Effect": "Allow", "Sid": "KMSPermissions" }, { "Action": [ "lambda:InvokeFunction" ], "Resource": "arn:aws:lambda:us-east-1:111122223333:function:post-extraction-lambda-function", "Effect": "Allow", "Sid": "LambdaPermissions" } ] } ``` ------ **An role policy to allow Amazon Q to run `PostExtractionHookConfiguration` without encryption.** ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Action": [ "s3:GetObject", "s3:PutObject" ], "Resource": [ "arn:aws:s3:::bucket-name", "arn:aws:s3:::bucket-name/*" ], "Effect": "Allow", "Sid": "S3GetObjectPermissions" }, { "Action": [ "s3:ListBucket" ], "Resource": [ "arn:aws:s3:::bucket-name" ], "Effect": "Allow", "Sid": "S3ListBucketPermissions" }, { "Action": [ "lambda:InvokeFunction" ], "Resource": "arn:aws:lambda:us-east-1:111122223333:function:post-extraction-lambda-function", "Effect": "Allow", "Sid": "LambdaPermissions" } ] } ``` ------ We recommend that you include `aws:sourceAccount` and `aws:sourceArn` in the trust policy. Their inclusion limits permissions and securely checks if `aws:sourceAccount` and `aws:sourceArn` are the same values as provided in the IAM role policy for the `sts:AssumeRole` action. This approach prevents unauthorized entities from accessing your IAM roles and their permissions. For more information, see [confused deputy problem](https://docs.aws.amazon.com//IAM/latest/UserGuide/confused-deputy.html) in the *IAM User Guide*. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Action": "sts:AssumeRole", "Sid": "QBusinessTrustPolicy", "Effect": "Allow", "Condition": { "StringLike": { "aws:SourceArn": "arn:aws:qbusiness:your-region:123456789012:application//index/" }, "StringEquals": { "aws:SourceAccount": "123456789012" } }, "Principal": { "Service": [ "qbusiness.amazonaws.com" ] } } ] } ``` ------ # IAM role for an Amazon Kendra retriever Amazon Kendra retriever When you use an Amazon Kendra index as a retriever, you must provide Amazon Q Business with an IAM role with permissions to access Amazon Kendra. You must also provide a trust policy that allows Amazon Q to assume the role. The following are the policies that must be provided. **To allow Amazon Q to access your Amazon Kendra index, use the following policy:** ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "KendraRetrieveAccess", "Effect": "Allow", "Action": [ "kendra:Retrieve", "kendra:DescribeIndex" ], "Resource": "arn:aws:kendra:us-east-1:111122223333:index/example-index-id" } ] } ``` ------ **To allow Amazon Q to assume a role, use the following trust policy:** ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AmazonQKendraAccessPermission", "Effect": "Allow", "Principal": { "Service": "qbusiness.amazonaws.com" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "aws:SourceAccount": "111122223333" }, "ArnEquals": { "aws:SourceArn": "arn:aws:qbusiness:us-east-1:111122223333:application/application-id" } } } ] } ``` ------