Setting up for Amazon Q Business

Before you begin using Amazon Q Business for the first time, complete the following tasks.

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.

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/ 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.

(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.

(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.

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 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 and store this in your Scripts directory. You can also set your Python directory as a Path or environment variable 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.

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 in the IAM Identity Center User Guide.

For regions and endpoints supported by Amazon Q Business, see Service quotas for Amazon Q Business.

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:

{
    "Version": "2012-10-17",
    "Statement": [{
        "Action": "qbusiness:*",
        "Effect": "Allow",
        "Resource": "*"
    }]
}

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"

To assign user subscriptions to applications, you must include permissions to call the necessary user subscription-related APIs. You don't call or use the APIs directly. The subscription-related APIs give permission to create, update, cancel, and view all user subscriptions for an application. Assigning user subscriptions is only available in the Amazon Q Business console.

To allow Amazon Q to assign user subscriptions, use the following role policy:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "QBusinessSubscriptionPermissions",
            "Effect": "Allow",
            "Action": [
                "qbusiness:UpdateSubscription",
                "qbusiness:CreateSubscription",
                "qbusiness:CancelSubscription",
                "qbusiness:ListSubscriptions"
            ],
            "Resource": [
             "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
             "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/subscription/{{subscription_id}}"
            ]
        },
        {
            "Sid": "QBusinessServicePermissions",
            "Effect": "Allow",
            "Action": [
                "user-subscriptions:UpdateClaim",
                "user-subscriptions:CreateClaim",
                "organizations:DescribeOrganizations",
                "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.

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 DisableAclOnDataSourceIAM action, review permissions in the IAM console.

As a best practice, we recommend you use an explicit deny on the DisableAclOnDataSourceIAM action and that you only grant the DisableAclOnDataSource permission when requested by Amazon Q administrators.

{
    "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.