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.

To sign up for an AWS account

1. Open https://portal.aws.amazon.com/billing/signup.

2. Follow the online instructions.

   Part of the sign-up procedure involves receiving a phone call 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.

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.

Secure your AWS account root user

1. Sign in to the AWS Management Console 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 in the AWS Sign-In User Guide.

2. 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) in the IAM User Guide.

Create a user with administrative access

1. Enable IAM Identity Center.

   For instructions, see Enabling AWS IAM Identity Center in the AWS IAM Identity Center User Guide.

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

2. Assign users to a group, and then assign single sign-on access to the group.

   For instructions, see Add groups 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 in the AWS Command Line Interface User Guide.

2. To configure the AWS CLI and set up a profile to call the AWS CLI, follow the instructions in Configuring the AWS CLI in the AWS Command Line Interface User Guide.

3. 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]: 

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

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, 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 (CMK), 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": [
                "*"
            ]
        }
    ]
}

For a complete list of IAM roles for Amazon Q Business, see IAM roles for Amazon Q Business.

Configure an IAM Identity Center instance

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

• Creating a same-region IAM Identity Center integration
• Creating a cross-region IAM Identity Center integration
• Understanding types of IAM Identity Center instances

Creating a same-region IAM Identity Center 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.

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. 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. For more information on IAM Identity Center instances and their use cases, see Understanding types of IAM Identity Center instances.

Creating a cross-region IAM Identity Center integration

Amazon Q Business can also integrate with IAM Identity Center in any commercial region where IAM Identity Center is available (excluding opt-in and special regions), even if that region isn’t one of the regions supported by Amazon Q Business. 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

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.

Once you opt-in, you will see the option to create a cross-region connection during the Amazon Q Business application creation process, as in the following image:

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.

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.

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

IAM Identity Center 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.

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.

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

• Prerequisites and considerations for setting up IAM Identity Center

• Confirm your identity sources in IAM Identity Center

• Get started with common tasks in IAM Identity Center

IAM Identity Center 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.

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.

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

• Enables account instances of IAM Identity Center

• Control account instance creation with Service Control Policies

• Create an account instance of IAM Identity Center

• Get started with common tasks in IAM Identity Center