# Configuring an Amazon Q Business application using AWS IAM Identity Center
As the first step towards creating a generative artificial intelligence (AI) assistant, you configure an application environment, and grant end user access to users to interact with an application environment using AWS IAM Identity Center for user management. Then you provision subscriptions for your IAM Identity Center users and groups.
Your authorized users interact with your application environment through the web experience. You share the endpoint URL of your web experience with your users, who open the URL and are authenticated before they can start chatting. The endpoint URL can be found in your web experience settings when selecting your application environment in the console.
This section guides you through the process of creating and configuring an Amazon Q Business application environment. To create an application environment, you can use the Amazon Q Business console, the AWS Command Line Interface (AWS CLI), and Amazon Q Business API operations.
As a prerequisite, make sure that you complete the [setting up](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html) tasks and go through the [configuring an IAM Identity Center instance](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/idc-setup.html) section. If you're using the AWS CLI or the API, make sure that you've created the required [IAM roles](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html).
After you finish creating your application environment, you can customize and preview the web experience that it will power.
**Note**
Response generation from large language model (LLM) knowledge is enabled by default for your application.
**Topics**
+ [
# Configuring an IAM Identity Center instance for an Amazon Q Business application
](idc-setup.md)
+ [
# Creating an Amazon Q Business application environment
](create-app.md)
+ [
# Migrating an Amazon Q Business direct SAML 2.0 application to IAM Identity Center
](migrate-application.md)
+ [
# Making authenticated Amazon Q Business API calls using IAM Identity Center
](making-sigv4-authenticated-api-calls.md)
+ [
# Managing Amazon Q Business application resources
](managing-resources.md)
# Configuring an IAM Identity Center instance for an Amazon Q Business application
Amazon Q Business integrates with IAM Identity Center to enable managing end user access to your Amazon Q Business application. IAM Identity Center is the recommended method for managing human access to AWS resources. We recommend enabling and pre-configuring an IAM Identity Center instance before creating your Amazon Q Business application.
**Topics**
+ [
## Prerequisites
](#idc-notes-create-application)
+ [
## Understanding types of IAM Identity Center instances
](#idc-instance-types)
+ [
## Creating a same-region integration
](#same-region-idc)
+ [
## Creating a cross-region integration
](#cross-region-idc)
## Prerequisites
Before you create an Amazon Q Business application, make sure you complete the following prerequisites:
+ [Enable an IAM Identity Center instance](https://docs.aws.amazon.com/singlesignon/latest/userguide/get-set-up-for-idc.html) and [connect 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.
**Note**
To minimize latency, we recommend using an IAM Identity Center instance created in the same region as your Amazon Q Business application. However, you can also use an IAM Identity Center instance created in an AWS region not yet supported by Amazon Q Business. For more information, see [Creating a cross-region IAM Identity Center instance](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/idc-setup).
+ [Configure an IAM Identity Center instance](https://docs.aws.amazon.com/singlesignon/latest/userguide/quick-start-default-idc.html) to connect to your Amazon Q Business application environment with users and groups added. You can also create and connect an IAM Identity Center instance to Amazon Q Business from the Amazon Q Business console. You can only add users to an IAM Identity Center instance created from the Amazon Q Business and not groups. To add groups, you need to use the IAM Identity Center console.
**Important**
If you add a user to a group in IAM Identity Center and have given that group access to your application, it can take up to 24 hours for the change to take effect and for the user to be able to access your Amazon Q Business application.
## Understanding types of IAM Identity Center instances
There are two types of IAM Identity Center instances: organization instances and account instances. Amazon Q supports both organization and account level IAM Identity Center instances.
**Important**
Amazon Q Business supports cross-region IAM Identity Center and Amazon Q Business integrations only for organization instances. Amazon Q Business doesn't support cross-region IAM Identity Center integrations for account level instances. Same-region Amazon Q Business and IAM Identity Center integrations are supported for both organization and account level instances.
The following section provides a brief overview of both instance types. For in-depth distinctions between the two and prerequisites for enabling them, see [Manage instances](https://docs.aws.amazon.com/singlesignon/latest/userguide/identity-center-instances.html) in the IAM Identity Center User Guide.
**Topics**
+ [
### Organization instances
](#idc-org-account-setup)
+ [
### Account instances
](#idc-account-instance-setup)
### Organization instances
When you enable IAM Identity Center in conjunction with AWS Organizations, you're creating an organization instance of IAM Identity Center. AWS Organizations is an account management service that enables you to consolidate multiple AWS accounts into an organization that you create and centrally manage. Your organization instance must be enabled in your management account and you can centrally manage the access of users and groups with a single organization instance. This is the AWS recommended approach to managing workforce identities.
To learn how to create and manage IAM Identity Center organization instances, see the following content in the IAM Identity Center User Guide:
+ [Enabling an organization instance of IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/get-set-up-for-idc.html)
+ [Prerequisites and considerations for setting up IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/get-started-prereqs-considerations.html)
+ [Confirm your identity sources in IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/prereq-identity-sources.html)
+ [Get started with common tasks in IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/getting-started.html)
### Account instances
If you don’t have plans to adopt IAM Identity Center for your entire organization, you can use an account instance of IAM Identity Center to manage user and group access to Amazon Q Business application. Account instances are bound to a single AWS account and are used only to manage user and group access for supported applications in the same account and AWS Region. You are limited to one account instance per AWS account. You can create an account instance from either of the following:
+ A member account in AWS Organizations.
+ A standalone AWS account that is not managed by AWS Organizations.
An account instance may fit your use case if:
+ You are trying out Amazon Q Business, and you haven’t yet decided that you want to deploy it to your entire organization.
+ You are the administrator of a single AWS account within an organization. Instead of waiting for the administrator of your organization to implement Amazon Q Business, you want to go ahead and do it just for the AWS account that you control.
+ Your enterprise is large, and does not have a single identity provider, or a single identity store, containing the entire user base that you want to give access to Amazon Q Business.
To learn how to create and manage IAM Identity Center account instances, see the following content in the IAM Identity Center User Guide:
+ [Account instances of IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/account-instances-identity-center.html)
+ [Enable an account instance of IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/enable-account-instance-console.html)
+ [Control account instance creation with Service Control Policies](https://docs.aws.amazon.com/singlesignon/latest/userguide/control-account-instance.html)
+ [Create an account instance of IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/create-account-instance.html)
+ [Get started with common tasks in IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/getting-started.html)
## Creating a same-region integration
If you don’t have an existing IAM Identity Center instance to integrate with Amazon Q Business, we recommend creating one in a [region Amazon Q Business is available in](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/quotas-regions.html#regions).
You can enable and configure an IAM Identity Center instance before you start to create your Amazon Q Business application in the IAM Identity Center console. If you pre-configure an IAM Identity Center instance, you add users and groups in the IAM Identity Center console. Then, during the application creation process, Amazon Q Business automatically detects—and connects to—your already configured IAM Identity Center instance. You add Amazon Q Business subscriptions to your IAM Identity Center users in the Amazon Q Business console.
Or, you can create an IAM Identity Center instance from within the Amazon Q Business console during the [Amazon Q Business application creation process](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html). If you choose this option, keep in mind that you can only create and add users to your application using this method. You can add groups you’ve already created in your IAM Identity Center instance, but can’t create them. All groups need to be created from the IAM Identity Center console.
Amazon Q Business supports same-region IAM Identity Center and Amazon Q Business integrations for both organization and account level instances.
## Creating a cross-region integration
Amazon Q Business, including Amazon Q Apps, can also integrate with IAM Identity Center in any [commercial region where IAM Identity Center is available](https://docs.aws.amazon.com/general/latest/gr/sso.html) (excluding opt-in and special regions), even if that region isn’t one of the [regions supported by Amazon Q Business](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/quotas-regions.html#regions). You can choose to create a cross-region integration if you already have an IAM Identity Center instance configured in a region that Amazon Q Business isn’t currently available in.
When you create a cross-region Amazon Q Business and IAM Identity Center-integration, you enable Amazon Q Business to make cross-region calls in order to access and store information from your IAM Identity Center instance, such as user and group attributes. This functionality allows Amazon Q Business to support IAM Identity Center-enabled applications in regions different from where your IAM Identity Center instance is ingested. When you create a cross-region integration, your Amazon Q Business application will have access to user and group information from an IAM Identity Center instance deployed in a different region. In these cross-region calls, Amazon Q Business might send the following user attributes:
+ Email address
+ Account in AWS Organizations
+ User ID
+ Group name
+ Group ID
**Important**
Amazon Q Business supports cross-region IAM Identity Center and Amazon Q Business integrations only for organization level instances. Amazon Q Business doesn't support cross-region IAM Identity Center integrations for account level instances. For more information on IAM Identity Center instance types and their use cases, see [Understanding types of IAM Identity Center instances](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html#idc-instance-types).
If you create a cross-region integration between an Amazon Q Business application and an IAM Identity Center instance, you may experience higher latency when using Amazon Q Business due to the increased overhead of making cross-region calls. The increase in latency will be proportional to the distance of the Amazon Q Business region from the IAM Identity Center region you're using. We recommend performing latency tests for your specific user case. We don't recommend using this feature if you have more than 100 groups per user in your IAM Identity Center instance.
When you create a cross-region IAM Identity Center and Amazon Q Business integration, any Amazon Q Business indices associated with your application are billed in the Amazon Q Business region they're created in. User subscriptions for an Amazon Q Business application using a cross-region IAM Identity Center integration are billed in the region the IAM Identity Center instance is created in. For more information on pricing, see [Amazon Q Business Pricing](https://aws.amazon.com/q/business/pricing).
Once you opt-in, you will see the option to create a cross-region connection during the [Amazon Q Business application creation process](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html), as in the following image:
![\[An console screenshot of the cross-region IDC enabling option.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/cross-region-idc.png)
# Creating an Amazon Q Business application environment
To create an Amazon Q Business application environment, you can use either the AWS Management Console or the Amazon Q Business API. When you create an application, response generation from large language model (LLM) knowledge is enabled by default.
As a prerequisite, make sure that you complete the [setting up](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html) tasks and go through the [Configuring an IAM Identity Center instance](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/idc-setup.html) section. If you're using the AWS CLI or the API, make sure that you've created the required [IAM roles](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html).
When you create an application environment, you can also choose to create a Amazon Q Business web experience. If you use the console to create an application environment, the web experience is created automatically, unless you choose otherwise. If you use the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateApplication.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateApplication.html) API operation to create an application environment, use the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateWebExperience.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateWebExperience.html) API operation to create your web experience.
When you create an application, you can also add any existing IAM Identity Center users and groups to your Amazon Q Business application. After you add users or groups to an application environment, you can then assign and choose [subscription tiers](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tiers.html) for each user or group. If you don't have an existing IAM Identity Center instance or user, you can create both of these from the Amazon Q Business console when you create your application. You can't create IAM Identity Center groups from the Amazon Q Business console.
**Important**
You must add, assign, and subscribe at least one user to your Amazon Q Business application environment for it to work as intended. For more information on user subscriptions for an IAM Identity Center-integrated Amazon Q Business application, see [Subscriptions for applications using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tiers.html#managing-sub-tiers-sso).
**Note**
As of Oct 31, 2024, once you have created a new Amazon Q Business application environment, the default web experience will allow users to interact directly with the LLM to get answers from its general knowledge or uploaded file content, even if the Admin has not yet connected any enterprise data sources.
For existing application environments, the *Allow direct access to LLM* setting will remain as previously configured. For new application environments, the *Allow direct access to LLM* setting will be enabled by default, though Admins can still disable this if desired.
For a consolidated view of your user subscriptions—including a list of subscribed users, their subscription status, and applications, accounts, or services a user can access through their subscriptions—see the [Amazon Q subscriptions page](https://console.aws.amazon.com/amazonq/subscriptions).
The following tabs provide a procedure for creating your Amazon Q Business application environment and adding subscriptions using the AWS Management Console and code examples for using the AWS CLI.
------
#### [ Console ]
**To create an application**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. On the **Create application** page, for **What kind of application do you want to build?**, enter the following information for your Amazon Q Business application:
1. **Application name** – A name for your Amazon Q Business application environment for easy identification. This name is only visible in the AWS Management Console. The name can include hyphens (-), but not spaces, and can have a maximum of 1,000 alphanumeric characters. Amazon Q Business auto-generates an application name for you, unless you choose to enter a custom name.
1. **Outcome** – Select **Web experience** to create a web experience for your application. Amazon Q Business creates a web experience by default when you create an application. If you don't want to create a web experience, unselect this option.
1. For **Access management method**, choose **IAM Identity Center (recommended)**. Then, complete the following steps:
1. (Optional) **Advanced IAM Identity Center settings – *optional*** – Activate **Enable cross-region calls** to allow Amazon Q Business to connect to an IAM Identity Center instance that exists in a region not already supported by Amazon Q Business. For more information, see [Creating a cross-region IAM Identity Center integration](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html#cross-region-idc).
1. Then, you will see the following options based on whether you have an IAM Identity Center instance already configured, or need to create one.
1. If you don't have an IAM Identity Center instance configured, you see the following:
1. The region your Amazon Q Business application environment is in.
1. **Specify tags for IAM Identity Center** – Add tags to keep track of your IAM Identity Center instance.
1. **Create IAM Identity Center** – Select to create an IAM Identity Center instance. Depending on your setup, you may be prompted to create either an account instance, or an organization instance, or be given the option to choose between creating an account instance and an organization instance. The console will display an ARN for your newly created resource after it's created.
1. If you have *both* an IAM Identity Center organization instance and an account instance configured, your instances will be auto-detected, and you see the following options:
1. ** [Organization instance of IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/organization-instances-identity-center.html)** – Select this option to manage access to Amazon Q Business by assigning users and groups from the Identity Center directory for your organization.
1. ** [Account instance of IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/organization-instances-identity-center.html)** – Select this option to manage access to Amazon Q Business by assigning existing users and groups from your Identity Center directory.
1. The region your Amazon Q Business application environment is in.
1. **IAM Identity Center** – The ARN for your IAM Identity Center instance.
1. If you have an IAM Identity Center account instance configured, your account instance will be auto-detected.
1. If you have an IAM Identity Center organization instance configured, your organization instance will be auto-detected.
1. If your IAM Identity Center instance is configured in an AWS region Amazon Q Business isn’t available in, and you haven’t activated cross-region IAM Identity Center calls, you will see a message saying that a connection is unavailable with an option to **Switch region**. Once you allow a cross-region connection between Amazon Q Business and IAM Identity Center using **Advanced IAM Identity Center settings**, your cross-region IAM Identity Center instance will be auto-detected by Amazon Q Business.
**Note**
Selecting **Switch region** will only give you the option to change your AWS Management Console region. To create a cross-region IAM Identity Center connection, use **Advanced IAM Identity Center settings**.
1. In **Quick start user – *optional***, do the following:
1. In **Select user**, choose from the following options:
1. If you've connected a pre-configured IAM Identity Center instance with users and groups already configured, Amazon Q Business detects the users and groups you have configured in IAM Identity Center. In this case, you can select **Choose a user** and, from the dropdown menu that opens, add users and groups directly from your IAM Identity Center directory.
1. If you've created a IAM Identity Center instance from within the Amazon Q Business console for your Amazon Q Business application, you can add a new user to your application and IAM Identity Center instance. Choose **Add new users and groups** and then complete the following steps:
1. In the **Add new users** dialog box that opens, enter the details of your user. Then select **Next** and **Add**.
**Note**
You can add multiple users by selecting **Add new user** and entering each user's details before you select **Add**.
Then, select **Assign**. The user is automatically added to an IAM Identity Center directory.
1. The details you must enter for each user include:
+ **Username** – A username is required for a user to sign into the AWS access portal. You can't change the username later. Maximum length 128 characters. Can only contain alphanumeric characters or any of the following: \$1=,.@-\$1
+ **First name** – First name of user.
+ **Last name** – Last name of user.
+ **Email address** – Email address of user.
+ **Confirm email address** – Enter email address again to confirm it.
+ **Display name** – The display name assigned to your user.
1. For **Select subscription** – Choose between **Q Business Pro** and **Q Business Lite**
**Note**
Amazon Q Business assigns Q Business Pro subscriptions to users and groups by default. To learn more about subscription tiers, see [User subscription tiers](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tiers.html#user-sub-tiers).
**Important**
If you add a user to a group in IAM Identity Center and have given that group access to your application, it can take up to 24 hours for the change to take effect and for the user to be able to access your Amazon Q Business application.
1. For **Application details** – Amazon Q Business chooses the following configuration settings for your application by default:
1. For **Application service access** – Amazon Q Business will create a new service-linked role for your application.
1. **Encryption** – Amazon Q Business will create an AWS owned AWS KMS key to encrypt your data.
1. **Web experience service access** – If you've chosen to create a web experience, Amazon Q Business creates a service access role to allow end users to log in to a Amazon Q Business web experience.
1. (Optional) To customize **Application details**, expand the **Application details section**, and then do the following:
1. In **Application service access**, for **Choose a method to authorize Amazon Q Business**, choose from the following options:
1. **Create and use a new service-linked role (SLR)** – Create and use a new Amazon Q Business-managed IAM role to allow it to access the AWS resources it needs to create your application.
1. **Create and use a new service role (SR)** – Create and use a new IAM role for Amazon Q Business to allow it to access the AWS resources it needs to create your application.
1. **Use an existing service role (SR)/service-linked role (SLR)** – Use an existing service role or service-linked IAM role to allow Amazon Q Business to access the AWS resources it needs to create your application.
**Note**
For more information about example service roles, see [IAM role for an Amazon Q Business application](create-application-iam-role.md). For information on service-linked roles, including to manage them, see [Using service-linked roles](https://docs.aws.amazon.com/amazonq/latest/business-use-dg/using-service-linked-roles.html).
1. **Service role name** – A name for the service (IAM) role you created for easy identification on the console.
1. For **Encryption** – Amazon Q Business encrypts your data by default using AWS managed AWS KMS keys. To customize your encryption settings, select **Customize encryption settings (advanced)**. Then, you can choose to use an existing AWS KMS key or create a new one.
1. In **Web experience service access**, enter the following information:
1. For **Choose a method to authorize Amazon Q Business** – A service access role assumed by end users when they sign in to your web experience that grants them permission to start and manage conversations Amazon Q Business. You can choose to use an existing role or create a new role.
1. **Service role name** – A name for the service role you created for easy identification on the console.
1. To start creating your application, choose **Create**.
**Note**
If you're creating a web experience, you can also choose to create your application and [view and customize your web experience](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/customizing-web-experience.html) by selecting **Create and open web experience**.
------
#### [ AWS CLI ]
**To configure an Amazon Q Business application **
```
aws qbusiness create-application \
--display-name application-name \
--identity-center-instance-arn identity-center-instance-arn \
--role-arn roleArn \
--description application-description \
--encryption-configuration kmsKeyId= \
--attachments-configuration attachmentsControlMode=ENABLED
```
**To add users to an application environment**
```
aws sso-admin create-application-assignment \
--application-arn idc-app-arn \
--principal-id idc-user-ID \
--principal-type USER
```
**To provision a user subscription**
```
aws qbusiness create-subscription \
--application-id application-id \
--principal user=idc-user-id \
--type subscription-type
```
**To add groups to an application environment**
```
aws sso-admin create-application-assignment \
--application-arn idc-app-arn \
--principal-id idc-group-ID \
--principal-type GROUP
```
**To provision a group subscription**
```
aws qbusiness create-subscription \
--application-id application-id \
--principal group=idc-group-id \
--type subscription-type
```
------
# Migrating an Amazon Q Business direct SAML 2.0 application to IAM Identity Center
**Important**
This content applies only to Amazon Q Business applications that need to migrate from using legacy SAML identity management to using IAM Identity Center for user access management.
To migrate an Amazon Q Business application connected directly to an external identity provider (IdP) to IAM Identity Center for user access management, follow the steps in this section.
If your existing external IdP application is connected to a [supported Amazon Q Business data source connector](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connectors-list.html) that already has access control (ACL) and identity crawling enabled, it's ready to migrate to IAM Identity Center. If your existing external IdP application is connected to a [supported Amazon Q Business data source connector](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connectors-list.html) that doesn't already have ACL or identity crawling enabled, you need to first enable these before you can begin migrating your application to IAM Identity Center. You do this by [updating your application](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-app-actions.html#update-app).
If you've not used IAM Identity Center before, Amazon Q Business will give you the option to create an IAM Identity Center instance from the Amazon Q Business console as part of the migration path. However, we recommend configuring an IAM Identity Center instance before migrating your existing SAML 2.0 compliant application to IAM Identity Center, especially if you're planning to connect your IAM Identity Center to an Active Directory or external identity provider. If you're managing users and groups in one identity source, changing to a different identity source might remove all user and group assignments.
For important information on creating an IAM Identity Center instance for your Amazon Q Business application, see [Configuring an IAM Identity Center instance](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/idc-setup.html).
The following tabs provide a procedure for migrating an existing, legacy SAML 2.0 based Amazon Q Business application to IAM Identity Center using the AWS Management Console and the AWS CLI.
**Topics**
+ [
## Migrating an application
](#migrating-application)
## Migrating an application
The following tabs provide a procedure for migrating your application on the AWS Management Console and code examples for the AWS CLI.
------
#### [ Console ]
**To migrate an Amazon Q Business application**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. In **Applications**, select the name of your SAML 2.0 integrated application from the list of applications.
1. In **Advanced IAM Identity Center settings**, activate **Enable cross-region calls** to access resources to allow Amazon Q Business to connect to an IAM Identity Center instance that exists in a region not already supported by Amazon Q Business. For more information, see [Creating a cross-region IAM Identity Center integration](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/idc-setup.html#cross-region-idc).
1. Then, depending on your Amazon Q Business application configuration you will see one of the following:
1. If the **Connect to IAM Identity Center** banner on the top of the page asks you to activate your ACL and identity crawling in preparation for migrating your application, you will need to activate ACL and identity crawling for the data sources connected to your application before migrating your application to IAM Identity Center. To do this, [update your application](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#update-datasources). Then, move to the next step.
1. If the **Connect to IAM Identity Center** banner on the top of the page displays a **Connect to IAM Identity Center** option, it means ACL and identity crawling are already enabled for your application and it's ready to migrate to IAM Identity Center. You can move to the next step.
1. From the **Connect to IAM Identity Center** banner on the top of the page, select **Connect to IAM Identity Center**.
1. In **Connect Amazon Q Business to IAM Identity Center**, you will see the following options based on whether you have an IAM Identity Center instance already configured, or need to create one.
1. If you don't have an IAM Identity Center instance configured, you see the following:
+ The region your Amazon Q Business application is in. This is so you can make sure that the region for your Amazon Q Business application and IAM Identity Center instance match.
+ **Specify tags for IAM Identity Center** – Add tags to keep track of your IAM Identity Center instance.
+ **Create IAM Identity Center** – Select to create a minimally-configured IAM Identity Center instance. The console will display an ARN for your newly created resource after it's created.
1. If you have *both* an IAM Identity Center organization instance and an account instance configured, your instances will be auto-detected, and you see the following options:
+ ** [Connect to organization instance of IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/organization-instances-identity-center.html)** – Select this option to manage access to Amazon Q Business by assigning users and groups from the Identity Center directory for your organization.
+ ** [Connect to account instance of IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/organization-instances-identity-center.html)** – Select this option to manage access to Amazon Q Business by assigning existing users and groups from your Identity Center directory.
+ The region your Amazon Q Business application is in. This is so you can make sure that the region for your Amazon Q Business application and IAM Identity Center instance match.
+ **IAM Identity Center** – The ARN for your IAM Identity Center instance.
1. If you have an IAM Identity Center account instance configured, your account instance will be auto-detected and you will see the following:
+ The region your Amazon Q Business application is in. This is so you can make sure that the region for your Amazon Q Business application and IAM Identity Center instance match.
+ **IAM Identity Center** – The ARN for your IAM Identity Center instance.
1. If you have an IAM Identity Center organization instance configured, you will see a message asking you to tell your admin to give you access to IAM Identity Center. You will need access to IAM Identity Center before you can proceed.
**Note**
If you plan to connect your IAM Identity Center to an Active Directory or external identity provider we recommend canceling this setup and configuring IAM Identity Center from the IAM Identity Center console. If you're managing users and groups in one identity source, changing to a different identity source might remove all user and group assignments.
1. From the application summary page, select **Groups and users**, and add users.
**Note**
If you plan to add groups to your application create these groups in IAM Identity Center before you create your application. If you don't have already configured IAM Identity Center groups, Amazon Q Business will redirect you to the IAM Identity Center console to configure groups before you can add them to your applicaton.
1. Then, from the application summary page, select **Migrate application** from the banner on the top of the page.
1. In the **Migrate application traffic** dialog box that opens, for **Service access**, choose an existing service role or create a new one. Amazon Q Business needs these permissions to access the resources it needs to migrate your application. For more information on the permissions required, see [IAM role for Amazon Q Business data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html).
1. Select **Migrate**.
When the migration is complete, the console displays a **Successfully migrated application traffic to IAM Identity Center** message.
------
#### [ AWS CLI ]
**To migrate an Amazon Q Business application**
**Before starting the migration process, confirm the presence of you web experience using the following command:**
```
aws qbusiness list-web-experiences \
--application-id application-id
```
If the `list-web-experiences` command returns a `webExperienceId`, you can proceed with migrating your application regardless of the status of the web experience.
**If the `list-web-experiences` command doesn't return a `webExperienceId`, you *must* create a new web experience before proceeding with migration using the following command:**
```
aws qbusiness create-web-experience \
--application-id application-id
```
**Then, update your Amazon Q Business application using the following command:**
```
aws qbusiness update-application \
--application-id application-id \
--identity-center-instance-arn idc-instance-arn
```
**Wait for your application status to change from `UPDATING` to `ACTIVE`. The response should include the `identityCenterApplicationArn` as one of the response fields. Check this is the case using the following command:**
```
aws qbusiness get-application \
--application-id application-id
```
**After your application status changes to `UPDATING`, add users and groups to your application using the following commands:**
To add users to an application
```
aws sso-admin create-application-assignment \
--application-arn idc-app-arn \
--principal-id idc-user-ID \
--principal-type USER
```
To add groups to an application
```
aws sso-admin create-application-assignment \
--application-arn idc-app-arn \
--principal-id idc-group-ID \
--principal-type GROUP
```
**Then, update your Amazon Q Business web experience using the following command:**
```
aws qbusiness update-web-experience \
--role-arn role-arn-value \
--application-id application-id \
--web-experience-id web-experience-id
```
**Note**
For IAM role permissions required, 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).
------
# Making authenticated Amazon Q Business API calls using IAM Identity Center
**Important**
**This documentation is for developers building custom applications that integrate with Amazon Q Business APIs.** These instructions help you create a trusted backend component in your custom application that can make authenticated API calls on behalf of your users. This is NOT for the built-in Amazon Q Business web experience — that handles authentication automatically through the AWS console.
Amazon Q Business can securely handle data with integrated authentication and authorization. During data ingestion, Amazon Q Business preserves the authorization information—access control lists (ACLs)—from the data source so users can only request answers from the data they already have access to. Through IAM Identity Center, Amazon Q Business uses [trusted identity propagation](https://docs.aws.amazon.com/singlesignon/latest/userguide/trustedidentitypropagation-overview.html) to ensure that an end user is authenticated and receives fine-grained authorization to their user ID and group-based resources.
In order to achieve this, a subset of the Amazon Q Business APIs ([Chat](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_Chat.html), [ChatSync](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ChatSync.html), [SearchRelevantContent](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_SearchRelevantContent.html), [ListConversations](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListConversations.html), [ListMessages](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListMessages.html), [DeleteConversation](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DeleteConversation.html), [PutFeedback](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_PutFeedback.html)) require identity-aware [AWS Sig V4 credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/signing-elements.html) for the authenticated user on whose behalf the API call is being made.
**Note**
This page provides an overview of the workflows needed to obtain AWS Sig V4 credentials for a user authenticated using an OIDC-compliant external identity provider (IdP), such as Okta. While we use Okta as an example, the same principles and steps apply to any other identity provider synced with your IAM Identity Center instance.
## Architecture overview
The following diagram shows how your custom application components interact with AWS services to make authenticated API calls:
![\[Sequence diagram showing a 12-step authentication flow for Amazon Q Business custom applications. The flow shows an end user accessing a custom app frontend, which requests Amazon Q Business data from the trusted backend. The backend exchanges tokens with an external IdP, IAM Identity Center, and AWS STS to obtain SigV4 credentials for authenticated API calls to Amazon Q Business APIs.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/qbusiness-sigv4-authentication-flow.png)
**Key components:**
+ **Custom app frontend**: Your user-facing application (web, mobile, etc.)
+ **Custom app trusted backend**: Your server-side component that handles AWS API calls
+ **External IdP**: Your identity provider (Okta, Azure AD, etc.)
+ **IAM Identity Center**: AWS service that manages identity federation
+ **Amazon Q Business APIs**: The APIs your application calls (`Chat`, `SearchRelevantContent`, etc.)
**Note**
Your custom application's backend component must implement this authentication flow. End users interact with your frontend, which communicates with your trusted backend to make Amazon Q Business API calls.
**Topics**
+ [
## Architecture overview
](#sigv4-architecture-overview)
+ [
## Prerequisites
](#sigv4-auth-api-calls-prereqs)
+ [
## One-time setup
](#control-plane-setup)
+ [
## Workflow for custom application backend API calls for an authenticated user
](#data-plane-workflow)
## Prerequisites
Before you begin setting up for making Sig V4 authenticated API calls, make sure you've done the following:
+ [Created an Amazon Q Business application](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html).
+ Created an Okta IdP instance and configured users and groups within it. While we use Okta as an example, the same principles and steps apply to any other OIDC-compliant external identity provider synced with your IAM Identity Center instance.
+ Created an IAM Identity Center instance for your Amazon Q Business application that uses Okta as your as the identity source.
+ [Synchronized the users and groups from Okta](https://docs.aws.amazon.com/singlesignon/latest/userguide/gs-okta.html#gs-ok-step4) with IAM Identity Center.
+ Configured access to the [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-quickstart.html).
## One-time setup
The following section outlines the steps to set up the Amazon Q Business control plane. You only need to perform these steps once.
1. Create an [OIDC app integration](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_oidc.htm) in Okta.
1. Then, in the IAM Identity Center instance you have created, create a [Trusted Token Issuer to trust IdP issuer with the issuer URL](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/sso-admin/create-trusted-token-issuer.html). For example, *https://.okta.com/oauth2/default*.
1. In your IAM Identity Center instance, create a [customer managed custom application](https://docs.aws.amazon.com/cli/latest/reference/sso-admin/create-application.html) using the following AWS CLI command:
```
aws sso-admin create-application \
--application-provider-arn arn:aws:sso::aws:applicationProvider/custom \
--instance-arn your-identity-center-arn \
--name your-custom-application-name
```
1. Then, [disable user assignment or provide explicit user assignments to the custom application](https://docs.aws.amazon.com/cli/latest/reference/sso-admin/put-application-assignment-configuration.html) you created using the following AWS CLI command:
```
aws sso-admin put-application-assignment-configuration \
--application-arn your-custom-application-arn \
--no-assignment-required
```
1. Then, add a JWT bearer grant to your application environment using the [put application environment grant](https://docs.aws.amazon.com/cli/latest/reference/sso-admin/put-application-grant.html) CLI command. For example:
```
aws sso-admin put-application-grant \
--cli-input-json '{
"ApplicationArn":"identity-center-custom-application-arn",
"Grant":{
"JwtBearer":{
"AuthorizedTokenIssuers":[
{
"AuthorizedAudiences":[
"idp-authorized-audience"
],
"TrustedTokenIssuerArn":"trusted-token-issuer-arn"
}
]
}
},
"GrantType":"urn:ietf:params:oauth:grant-type:jwt-bearer"
}'
```
1. You will then need to add an authentication method for a Amazon Q Business application environment using the [put application environment authentication method](https://docs.aws.amazon.com/cli/latest/reference/sso-admin/put-application-authentication-method.html) AWS CLI command:
```
aws sso-admin put-application-authentication-method \
--cli-input-json '{
"ApplicationArn": "identity-center-custom-application-arn",
"AuthenticationMethod": {
"Iam": {
"ActorPolicy": {
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": {
"AWS": "your-aws-account-id",
"Service": "qbusiness.amazonaws.com"
},
"Action": [
"sso-oauth:CreateTokenWithIAM"
],
"Resource": "your-identity-center-custom-application-arn",
"Condition": {
"ArnEquals": {
"aws:SourceArn": "arn:${ArnPartition}:${Service}:${Region}:${AppAccountId}:${Resource}"
},
"StringEquals": {
"aws:SourceAccount": "${AppAccountId}"
}
}
}]
}
}
},
"AuthenticationMethodType": "IAM"
}'
```
1. Next, add a list of authorized targets for an IAM Identity Center access scope for an Amazon Q Business application environment using the following [put application environment access scope](https://docs.aws.amazon.com/cli/latest/reference/sso-admin/put-application-authentication-method.html) AWS CLI command:
```
aws sso-admin put-application-access-scope \
--application-arn identity-center-custom-application-arn \
--scope "qbusiness:conversations:access"
```
1. Then, create an IAM role that your application environment will use to call [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) API with the following policies:
**Trust policy**
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [{
"Sid": "QCLITrustPolicy",
"Effect": "Allow",
"Principal": {
"Service": [
"qbusiness.amazonaws.com"
]
},
"Action": [
"sts:AssumeRole",
"sts:SetContext"
],
"Condition": {
"StringEquals": {
"aws:SourceAccount": "111122223333"
}
}
}]
}
```
------
**Permissions policy**
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "QBusinessConversationPermission",
"Effect": "Allow",
"Action": [
"qbusiness:Chat",
"qbusiness:ChatSync",
"qbusiness:ListMessages",
"qbusiness:ListConversations",
"qbusiness:DeleteConversation",
"qbusiness:PutFeedback",
"qbusiness:GetWebExperience",
"qbusiness:GetApplication",
"qbusiness:ListPlugins",
"qbusiness:GetChatControlsConfiguration",
"qbusiness:GetMedia"
],
"Resource": "arn:aws:qbusiness:us-east-1:111122223333:application/application-id"
},
{
"Sid": "QBusinessKMSDecryptPermissions",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:us-east-1:111122223333:key/key-id"
]
},
{
"Sid": "QBusinessSetContextPermissions",
"Effect": "Allow",
"Action": "sts:SetContext",
"Resource": "arn:aws:sts:*:111122223333:assumed-role/role-name/session-name"
}
]
}
```
------
1. Then, get the list of synced users and groups in your IAM Identity Center-integrated Amazon Q Business application using the following AWS CLI command:
```
aws sso-admin list-application-assignments \
--application-arn your-custom-application-arn
```
1. Finally, add a subscription for each user or group in your IAM Identity Center-integrated Amazon Q Business application using the following AWS CLI commands:
**To provision a user subscription**
```
aws qbusiness create-subscription \
--application-id application-id \
--principal user=idc-user-id \
--type subscription-type
```
**To provision a group subscription**
```
aws qbusiness create-subscription \
--application-id application-id \
--principal group=idc-group-id \
--type subscription-type
```
## Workflow for custom application backend API calls for an authenticated user
After you've completed the [one-time setup](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/making-sigv4-authenticated-api-calls.html#control-plane-setup) tasks, you can use one of two workflows to generate identity-aware credentials to make API calls for your IAM Identity Center-integrated Amazon Q Business application:
+ the AWS SDK trusted identity propagation plugin (TIP\$1 workflow (recommended), or a longer API workflow.
+ The API workflow requires a manual token exchange with IAM Identity Center and uses AWS STS to generate identity-aware credentials for your Amazon Q Business application.
The AWS SDK TIP plugin workflow streamlines the authorization process by eliminating the need for manual token exchange and credential generation. Once set up, it automatically handles token exchange and credential management.
The TIP plugin workflow is the recommended approach for implementing identity-aware authorization. It is currently supported by the Java and JavaScript SDK. For more information, see [Trusted identity propagation (TIP) plugin](https://docs.aws.amazon.com/sdkref/latest/guide/access-tip.html) in the *AWS SDKs and Tools Reference Guide*.
### (Recommended) Using an SDK plugin workflow
Use the Java or JavaScript SDK to create the plugin and make calls to Amazon Q Business using the following:
+ `webTokenProvider` – A function that the customer implements to obtain an OpenID token from their external identity provider.
+ `accessRoleArn` – The IAM role ARN to be assumed by the plugin with the user's identity context to get the identity-enhanced credentials.
+ `applicationArn` – The unique identifier string for the client or application. This value is an application ARN that has OAuth grants configured.
+ `applicationRoleArn` – The IAM role ARN to be assumed with `AssumeRoleWithWebIdentity` so that the OIDC and AWS STS clients can be bootstrapped. If `applicationRoleArn` is not provided, it is mandatory to provide both `ssoOidcClient` and `stsClient` parameters.
+ `ssoOidcClient` – An IAM Identity Center OIDC client, such as `SsoOidcClient` for Java or `client-sso-oidc` for Javascript, with customer-defined configurations. If not provided, an OIDC client using `applicationRoleArn` will be instantiated and used.
+ `stsClient` – An AWS STS client with customer-defined configurations, used to assume `accessRoleArn` with the user's identity context. If not provided, an AWS STS client using `applicationRoleArn` will be instantiated and used.
If both `ssoOidcClient` and `stsClient`, and `applicationRoleArn` are provided, the former is prioritized.
```
// Option-1: Build and pass OIDC and STS clients
SsoOidcClient oidcClient = SsoOidcClient.builder()
.region(Region.US_EAST_1)
.credentialsProvider(credentialsProvider).build();
StsClient stsClient = StsClient.builder()
.region(Region.US_EAST_1)
.credentialsProvider(credentialsProvider).build();
TrustedIdentityPropagationPlugin trustedIdentityPropagationPlugin = TrustedIdentityPropagationPlugin.builder()
.webTokenProvider(() -> webToken)
.applicationArn(idcApplicationArn)
.accessRoleArn(accessRoleArn)
.ssoOidcClient(client)
.stsClient(stsClient)
.build();
// Option-2: Pass applicationRoleArn and defer the STS & OIDC clients creation to the plugin
TrustedIdentityPropagationPlugin trustedIdentityPropagationPlugin = TrustedIdentityPropagationPlugin.builder()
.webTokenProvider(() -> webToken)
.applicationArn(idcApplicationArn)
.accessRoleArn(accessRoleArn)
.applicationRoleArn(applicationRoleArn)
.build();
QBusinessClient qBusinessClient = QBusinessClient.builder()
.region(Region.US_EAST_1)
.addPlugin(trustedIdentityPropagationPlugin)
.build();
// Create ChatSyncRequest
ChatSyncRequest chatSyncRequest = ChatSyncRequest.builder()
.applicationId(applicationId)
.userMessage(userMessage)
// You can add conversationId, attachments, chatMode, etc. here
.build();
// Call chatSync operation
ChatSyncResponse chatSyncResponse = qBusinessClient.chatSync(chatSyncRequest);
```
### Using an API workflow
1. First, use the [CreateTokenWithIAM](https://docs.aws.amazon.com/singlesignon/latest/OIDCAPIReference/API_CreateTokenWithIAM.html) API call to obtain an IAM Identity Center-provided JWT bearer grant token using your:
+ `clientID`: Your IAM Identity Center custom application environment ARN.
+ `grantType`: For example, *'urn:ietf:params:oauth:grant-type:jwt-bearer'*.
+ `assertion`: The user authenticated ID token obtained from Okta.
1. Then, use the [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) API call to obtain user decorated AWS Sig V4 credentials using your:
+ `RoleArn`: The IAM role ARN.
+ `RoleSessionName`: A unique session name.
+ `DurationSeconds`: The session duration in seconds.
+ `ProvidedContexts`: A list of previously acquired trusted context assertions in the format of a JSON array. The trusted context assertion is signed and encrypted by AWS STS. For example:
```
[{
'ProviderArn': "arn:aws:iam::aws:contextProvider/IdentityCenter",
'ContextAssertion': claims["sts:identity_context"]
}]
```
**Note**
The `ContextAssertion` uses the “sts:identity\$1context” object from the claims object of the decoded JWT bearer grant token obtained as part of Step 1 in this procedure.
1. Use the identity-aware AWS Sig V4 credentials in the previous step to initialize the AWS SDK client and then make Amazon Q Business API calls using that client.
First, set the following environment variables in your command line environment:
```
AWS_ACCESS_KEY_ID="identity-aware-sigv4-access-key"
AWS_SECRET_ACCESS_KEY="identity-aware-sigv4-secret-key"
AWS_SESSION_TOKEN="identity-aware-sigv4-session-token"
```
Then, run the following Python script from the same window:
```
import boto3
import json
import random
import boto3
aq_client = boto3.client(
"qbusiness",
region_name="your-aws-region"
)
resp = aq_client.chat_sync(
applicationId = "amazon-qbusiness-application-id",
userMessage = "chat-request",
clientToken = str(random.randint(0,10000)
)
print(f"Amazon Q Business response: {resp["systemMessage"]}")
```
**Important**
As a security best practice, the credentials should not be hard coded in your scripts or code. For more information, refer to [Boto 3 documentation on using credentials](https://boto3.amazonaws.com/v1/documentation/api/1.9.156/guide/configuration.html).
# Managing Amazon Q Business application resources
You can choose to manage your Amazon Q Business application environment and associated resources. To learn how to do so, see the following sections:
+ [Managing Amazon Q Business applications](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-app-actions.html)
+ [Managing Amazon Q Business web experiences](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-exp-actions.html)
+ [Managing user subscriptions](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/manage-user-subscriptions.html)
+ [Tagging resources](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tagging.html)
# Managing Amazon Q Business applications
To manage an Amazon Q Business application environment, you can take the following actions:
**Topics**
+ [
## Deleting an application
](#delete-app)
+ [
## Getting application environment properties
](#describe-app)
+ [
## Listing applications
](#list-app)
+ [
## Updating an application environment
](#update-app)
## Deleting an application
To delete an Amazon Q Business application environment, you can use the console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DeleteApplication.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DeleteApplication.html) API operation.
The following tabs provide a procedure for the console and code examples for the AWS CLI.
------
#### [ Console ]
**To delete an Amazon Q Business application**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. In **Applications**, choose **Actions**.
1. Choose **Delete**.
1. In the dialog box that opens, type **Delete** to confirm deletion, and then choose **Delete**.
You are returned to the service console while your application environment is deleted. When the deletion process is complete, the console displays a message confirming successful deletion.
------
#### [ AWS CLI ]
**To delete an Amazon Q Business application environment**
```
aws qbusiness delete-application \
--application-id application-id
```
------
## Getting application environment properties
To get the properties of an Amazon Q Business application environment, you can use the console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_GetApplication.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_GetApplication.html) API operation.
The following tabs provide a procedure for the console and code examples for the AWS CLI.
------
#### [ Console ]
**To get properties of an Amazon Q Business application environment**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. For **Applications**, select the name of your application environment from the list of applications.
1. On **Application settings**, the following properties are available:
+ **Application name** – The name that you chose for your application environment.
+ **Application ID** – The ID assigned to your application environment.
+ **Subtitle** – The subtitle that you chose to assign to your application environment.
+ **Service access** – The service access role that your application environment is using.
+ **Title** – The title that you gave to your application environment.
+ **Application status** – The status of your application environment.
To update a setting, select **Edit**.
------
#### [ AWS CLI ]
**To get Amazon Q Business application properties **
```
aws qbusiness get-application \
--application-id application-id
```
------
## Listing applications
To list Amazon Q Business applications, you can use the console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListApplications.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListApplications.html) API operation.
The following tabs provide a procedure for the console and code examples for the AWS CLI.
------
#### [ Console ]
**To list your Amazon Q Business application environments**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. In **Applications**, all your configured application environments are listed.
------
#### [ AWS CLI ]
**To list Amazon Q Business application environments **
```
aws qbusiness list-applications \
--max-results max-results-to-return
```
------
## Updating an application environment
To update an Amazon Q Business application environment, you can use the console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateApplication.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateApplication.html) API operation.
**Note**
You can't update the retriever you've chosen or change users and groups added to the application environment when you update it. If you need to update your retriever, create a new application environment.
If you're integrating your Amazon Q Business application environment with IAM Identity Center (IDC) and you want to update users and groups, you can do so from the [application environment summary](https://docs.aws.amazon.com/amazonq/latest/business-use-dg/supported-app-actions.html) page.
The following tabs provide a procedure for the console and code examples for the AWS CLI.
------
#### [ Console ]
**To update an Amazon Q Business application environment**
**Option 1**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. In **Applications**, select the name of your application environment from the list of applications.
1. In **Applications**, choose **Actions**.
1. Choose **Edit**.
On the **Update application** page, edit your application environment settings.
**Option 2**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. In **Applications**, select the name of your application environment from the list of applications.
1. On the application page, select **Edit** from the page header, or select **Edit** from **Application settings**.
1. Choose **Edit**.
On the **Update application** page, edit your application environment settings.
------
#### [ AWS CLI ]
**To update an Amazon Q Business application environment **
```
aws qbusiness update-application \
--application-id application-id \
--display-name application-name \
--role-arn roleArn \
--description application-description \
--attachments-configuration attachmentsControlMode=ENABLED
```
------
# Managing Amazon Q Business web experiences
To manage Amazon Q Business web experiences, you can take the following actions:
**Topics**
+ [
## Creating a web experience
](#create-experience)
+ [
## Deleting a web experience
](#delete-web-experience)
+ [
## Getting properties of a web experience
](#describe-web-experience)
+ [
## Listing web experiences
](#list-web-experiences)
+ [
## Updating a web experience
](#update-web-experience-idp)
## Creating a web experience
To create an Amazon Q Business web experience, you can use the console or the [CreateWebExperience](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateWebExperience.html) API operation.
The following tabs provide a procedure for the AWS Management Console and code examples for the AWS CLI.
------
#### [ Console ]
If you use the console, this action is spread across two steps: [Configuring an Amazon Q Business application using AWS IAM Identity Center](create-application.md) and [Customizing web experience](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/customizing-web-experience-app.html). To create a web experience, you must create an application environment.
------
#### [ AWS CLI ]
**To create an Amazon Q Business web experience**
```
aws qbusiness create-web-experience \
--application-id application-id \
--sample-prompts-control-mode sample-prompts \
--subtitle subtitle \
--tags tags \
--title title \
--welcome-message welcome-message \
```
------
## Deleting a web experience
To delete an Amazon Q Business web experience, you can use the console or the [DeleteWebExperience](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DeleteWebExperience.html) API operation.
If you're using the API, you can delete a web experience without deleting the application environment that it's a part of.
If you're using the console, the only way to delete your Amazon Q Business web experience is to delete the Amazon Q Business application environment that it's attached to.
The following tabs provide a procedure for the AWS Management Console and code examples for the AWS CLI.
------
#### [ Console ]
**To delete an Amazon Q Business web experience**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. In **Applications**, choose **Actions**.
1. Choose **Delete**.
1. In the dialog box that opens, type **Delete** to confirm deletion, and then choose **Delete**.
You are returned to the service console while your application environment is deleted. When the deletion process is complete, the console displays a message confirming successful deletion. Both the application environment and the web experience are deleted.
------
#### [ AWS CLI ]
**To delete an Amazon Q Business web experience**
```
aws qbusiness delete-web-experience \
--application-id application-id \
--web-experience-id web-experience-id
```
------
## Getting properties of a web experience
To get the properties of an Amazon Q Business web experience, you can use the console or the [GetWebExperience](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_GetWebExperience.html) API operation.
The following tabs provide a procedure for the AWS Management Console and code examples for the AWS CLI.
------
#### [ Console ]
**To get properties of an Amazon Q Business web experience **
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. In **Applications**, select the name of your application environment from the list of applications.
1. For **Web experience settings**, the following settings are available:
+ **Web experience IAM role ARN** – The IAM role assumed by end users when they log in to your web experience.
+ **Deployed URL** – The deployed URL of your web experience.
+ **Tags** – Tags that are attached to your web experience.
To update a setting, choose **Edit**.
------
#### [ AWS CLI ]
**To get properties of an Amazon Q Business web experience**
```
aws qbusiness get-web-experience \
--application-id application-id \
--web-experience-id web-experience-id
```
------
## Listing web experiences
To list Amazon Q Business web experiences, you can use the console or the [ListWebExperiences](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListWebExperiences.html) API operation.
If you use the console, you can only see the web experience that's attached to a single application environment.
The following tabs provide a procedure for the AWS Management Console and code examples for the AWS CLI.
------
#### [ Console ]
**To list Amazon Q Business web experiences**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. For **Applications**, the Amazon Q Business web experience attached to your application environment is shown.
------
#### [ AWS CLI ]
**To list Amazon Q Business web experiences**
```
aws qbusiness get-web-experience \
--application-id application-id \
--web-experience-id web-experience-id \
--max-results max-results-to-return
```
------
## Updating a web experience
To update an Amazon Q Business web experience, you can use the console or the [UpdateWebExperience](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateWebExperience.html) API operation.
The following tabs provide a procedure for the AWS Management Console and code examples for the AWS CLI.
------
#### [ Console ]
**To update an Amazon Q Business web experience**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. In **Applications**, select the name of your application environment from the list of applications.
1. Select **Customize web experience**.
1. Expand the right navigation menu to edit your web experience settings.
------
#### [ AWS CLI ]
**To update an Amazon Q Business web experience**
```
aws qbusiness update-web-experience \
--application-id application-id \
--web-experience-id web-experience-id \
--authentication-configuration authentication-configuration \
--sample-prompts-control-mode sample-prompts \
--subtitle subtitle \
--title title \
--welcome-message welcome-message
```
------
# Managing user subscriptions for IAM Identity Center-integrated applications
To manage user subscriptions added to an application environment, you can perform the following actions:
**Topics**
+ [
## Updating user subscriptions
](#update-user-subscriptions)
+ [
## Canceling user or group subscriptions
](#delete-user-subscriptions)
+ [
## Listing user subscriptions
](#list-user-subscriptions)
## Updating user subscriptions
To update a subscription in an Amazon Q Business application, you can use either the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateSubscription.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateSubscription.html) API operation.
For more information on user subscriptions for an IAM Identity Center-integrated Amazon Q Business application, see [Subscriptions for applications using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tiers.html#managing-sub-tiers-sso).
------
#### [ Console ]
**To update user or group subscription tier**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. In **Applications**, select the name of the application environment you created.
1. From your applications page, from the **User access** section, select **Manage user access**.
1. From **Manage access and subscriptions** select the subscription you want to update. Then, select **Edit subscription**.
1. In the **Confirm subscription change** dialog box that opens, from the **New subscription** dropdown select **Q Business Lite** or **Q Business Pro**.
1. Then, select **Confirm**. You will see the subscription status notification change next to the user you've added the subscription to.
1. Then, select **Confirm** to save your changes.
------
#### [ AWS CLI ]
**To update user or group subscription tier**
```
aws qbusiness update-subscription \
--application-id application-id \
--subscription-id subscription-id \
--type subscription-type
```
------
## Canceling user or group subscriptions
To cancel subscriptions, you can use the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CancelSubscription.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CancelSubscription.html) API operation.
When you unsubscribe and remove a user or group, it unsubscribes them from the application environment and removes them from the user list.
For more information on user subscriptions for an IAM Identity Center-integrated Amazon Q Business application, see [Subscriptions for applications using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tiers.html#managing-sub-tiers-sso).
------
#### [ Console ]
**To unsubscribe a user or group from an Amazon Q Business application environment**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. In **Applications**, select the name of the application environment you created.
1. From your applications page, from the **User access** section, select **Manage user access**.
1. From **Manage access and subscriptions** select the user or group subscription you want to update. Then, select **Remove and unsubscribe**.
1. Then, from the **Unsubscribe and remove** dialog box, **Confirm**.
1. Then, select **Confirm** to save your changes.
This step cancels subscriptions for the selected users and groups and also removes them from your Amazon Q Business application environment.
**Note**
To stop subscription charges for a user, ensure you have unsubscribed that user from all Amazon Q Business application environments and Quick instances. For instructions on how to unsubscribe a user from Quick, see [Unsubscribing from Quick Q](https://docs.aws.amazon.com/quicksight/latest/user/quicksight-q-unsubscribe.html) in the Quick User Guide.
To stop charges for an Amazon Q Business index, you must delete either your Amazon Q Business index or [delete your Amazon Q Business application environment](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-app-actions.html#delete-app). If you use the console, deleting your application environment is the only way to delete an index associated with it.
------
#### [ AWS CLI ]
**To cancel user or group subscriptions to Amazon Q Business**
```
aws qbusiness cancel-subscription \
--application-id application-id \
--subscription-id subscription-id \
--type subscription-type
```
------
## Listing user subscriptions
To see a list of user and group subscriptions within a specific Amazon Q Business application, you can use the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListSubscriptions.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListSubscriptions.html) API operation.
For a consolidated view of your user subscriptions—including a list of subscribed users, their subscription status, and applications, accounts, or services a user can access through their subscriptions—you can also view the [Amazon Q subscriptions page](https://console.aws.amazon.com/amazonq/subscriptions).
------
#### [ Console ]
**To view a list of user and group subscriptions in an Amazon Q Business application environment**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. In **Applications**, select the name of the application environment you created.
1. From your applications page, from the **User access** section, select **Manage user access**.
1. In the **Manage access and subscriptions** select **Users** if you want to view user subscriptions or **Groups** if you want to list group subscriptions.
**To view a consolidated list of all user and group subscriptions across all Amazon Q Business application environments**
1. Sign in to the AWS Management Console and open the Amazon Q console.
1. From the left navigation menu, choose **Subscriptions**,and then select **Users** if you want to view user subscriptions or **Groups** if you want to list group subscriptions.
------
#### [ AWS CLI ]
**To list user or group subscriptions in an Amazon Q Business application**
```
aws qbusiness list-subscriptions \
--application-id application-id
```
**To list user or group subscriptions across all Amazon Q Business applications**
This action is not supported.
------
# Tagging Amazon Q Business resources
Manage your Amazon Q Business applications and web experiences by assigning tags. You can use tags to categorize your Amazon Q Business resources in various ways. For example, you could categorize by purpose, owner, or application, or any combination. Each tag consists of a *key* and a *value*, both of which you define.
Tags help you to do the following:
+ **Identify and organize your AWS resources** – Many AWS services support tagging, so you can assign the same tag to resources in different services to indicate that the resources are related. For example, you can tag an Amazon Kendra retriever and the Amazon Q Business web experience that uses the retriever with the same tag.
+ **Allocate costs** – You activate tags on the AWS Billing and Cost Management dashboard. AWS uses tags to categorize your costs and deliver a monthly cost allocation report to you. For more information, see [Cost Allocation and Tagging](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/cost-alloc-tags.html) in the *AWS Billing User Guide*.
+ **Control access to your resources** – You can use tags in AWS Identity and Access Management (IAM) policies that control access to Amazon Q Business resources. To activate tag-based access control, you can attach these policies to an IAM role or IAM user. For more information, see [Authorization based on tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/security_iam_service-with-iam.html#security_iam_service-with-iam-tags).
You can create and manage tags using the AWS Management Console, the AWS Command Line Interface (AWS CLI), or the Amazon Q Business API.
**Topics**
+ [
## Using tags
](#tagging-resources)
+ [
## Tag restrictions
](#tag-restrictions)
## Using tags
If you're using the console, you can tag resources when you create them or add them later. You can also use the console to update or remove tags in the following ways:
------
#### [ Adding tags ]
**To add Amazon Q Business tags**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. From **Applications**, select the application whose resources you want to tag.
1. From the application summary page, scroll down and select **Tags**.
1. In **Tags**, from the resource you want to add tags to, select **Manage tags**.
1. In **Tags – *optional***, select **Add new tag** to add tags to your Amazon Q Business resource. Then, enter the following information for each tag:
+ **Key** – Add a key for your tag.
+ **Value - *optional*** – An optional value for your tag.
1. Select **Save**.
------
#### [ Removing tags ]
**To remove tags**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. From **Applications**, select the application you want to delete tags from.
1. From the application summary page, scroll down and select **Tags**.
1. In **Tags**, from the resource you want to add tags to, select **Manage tags**.
1. In **Tags – *optional***, select **Remove**.
1. Select **Save**.
------
#### [ Listing tags ]
**To view a list of tags**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. From **Applications**, select the application you want to delete tags from.
1. From the application summary page, scroll down and select **Tags**.
1. In **Tags**, each tagged resource will display a list of tags associated with it.
------
If you're using the AWS CLI or the Amazon Q Business API, use the following operations to manage tags for your resources:
+ [CreateApplication](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateApplication.html) – Apply tags when you create an Amazon Q Business application.
+ [CreateWebExperience](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateWebExperience.html) – Apply tags when you create an Amazon Q Business web experience.
+ [ListTagsForResource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListTagsForResource.html) – View the tags associated with a resource.
+ [TagResource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_TagResource.html) – Add and modify tags for a resource.
+ [UntagResource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UntagResource.html) – Remove tags from a resource.
## Tag restrictions
The following restrictions apply to tags on Amazon Q Business resources:
+ Maximum number of tags – 50
+ Maximum key length – 128 characters
+ Maximum value length – 256 characters
+ Valid characters for key and value – a–z, A–Z, space, and the following characters: \$1 . : / = \$1 - and @
+ Keys and values are case sensitive
+ Don't use `aws:` as a prefix for keys; it's reserved for AWS use