Creating a sample Amazon Q Business application
This section guides you through creating an Amazon Q Business sample application
using IAM Identity Center for managing user access to your application.
Before you create a fully-configured Amazon Q Business application, you can choose
to create a sample application to test how Amazon Q Business works. A sample
application supports only upload file and chat conversations when created, is powered by an
Amazon Q Business native retriever, and doesn't have to be connected to Amazon Q Business data sources. Amazon Q Business sample applications are
automatically integrated with AWS IAM Identity Center for user access management.
You can choose to update a sample application to a fully-configured application at any
time by selecting a retriever, an index type, connecting data sources, and enhancing it when
you update it.
As a prerequisite, make sure that you complete the setting
up tasks and go through the connecting an
IAM Identity Center instance section. If you're using the AWS CLI or the API, make sure that you
created the required IAM roles.
Prerequisites
Before you create an Amazon Q Business application, make sure you complete the
following prerequisites:
-
Enable an IAM Identity Center instance and connect the identity source for your Amazon Q Business
application environment in IAM Identity Center. Amazon Q Business supports both organization and account level
IAM Identity Center instances.
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.
-
Configure an IAM Identity Center instance 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.
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.
Step 1: Create a sample application
This section guides you through the process of creating a sample Amazon Q Business application. To do this, you can use the Amazon Q Business console, the
AWS Command Line Interface (AWS CLI), and the Amazon Q Business API operations.
- Console
-
To create an application
-
Sign in to the AWS Management Console and open the Amazon Q Business
console.
-
From the How it works menu, from
Experiment with a sample –
optional, choose
Try quick application.
-
On the Create application page, for
Application settings, enter the following
information for your Amazon Q Business application:
-
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.
-
In Service access, for Choose a
method to authorize Amazon Q Business, choose
from the following options:
-
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.
-
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.
-
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.
-
Service role name – A name for
the service (IAM) role you created for easy
identification on the console.
-
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.
-
For Access management method –
choose IAM Identity Center.
-
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.
-
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.
-
If you don't have an IAM Identity Center instance configured, you see
the following:
-
The region your Amazon Q Business
application environment is in.
-
Specify tags for IAM Identity Center
– Add tags to keep track of your IAM Identity Center
instance.
-
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.
-
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:
-
Organization
instance of IAM Identity Center –
Select this option to manage access to Amazon Q Business by assigning users and groups from
the Identity Center directory for your
organization.
-
Account instance
of IAM Identity Center – 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 environment is in.
-
IAM Identity Center – The ARN for
your IAM Identity Center instance.
-
If you have an IAM Identity Center account instance configured, your
account instance will be auto-detected.
-
If you have an IAM Identity Center organization instance configured, your
organization instance will be auto-detected.
-
If your IAM Identity Center instance is configured in an AWS region Amazon Q Business isn’t available in, and you haven’t completed Step 7 of this procedure, you
will see a message saying that a connection is unavailable with an option to
Switch region. Once you complete Step 7, a cross-region
connection between Amazon Q Business and IAM Identity Center will be automatically
established and your cross-region instance will be auto-detected.
Selecting Switch region will only give you the option
to change your AWS Management Console region. To create a cross-region IAM Identity Center and Amazon Q Business integration follow Step 6 of this procedure.
-
Tags – optional
– To add tags to your Amazon Q Business application environment and
web experience, select Add new tag. Then, enter
the following information for each tag:
For more information about using tags with Amazon Q Business, see Tags.
-
To start creating your application, choose
Create.
- 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
\
--enryption-configuration kmsKeyId=<kms-key-id>
\
--attachments-configuration attachmentsControlMode=ENABLED
Step 2: Add users and groups
In this step you add users and groups to your sample application. You need to add and
subscribe at least one user to your sample application for it to work as
intended.
The following tabs provide a procedure for the AWS Management Console and code examples for the
AWS CLI.
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.
- Console
-
To add users and groups with their subscriptions to
your Amazon Q Business application
-
To add users or groups, from Manage access,
select the Users or Groups
tab, then select Add groups and users. Then,
depending on how you're integrating Amazon Q Business with IAM Identity Center, do
the following:
-
If you're using a pre-configured IAM Identity Center instance with
users and groups already configured, Amazon Q Business detects the
users you have configured in IAM Identity Center. You can choose to assign
users from your IAM Identity Center directory.
-
In this case, in the Add or assign users
and groups dialog box that opens,
select Assign existing users and
groups. Then, select
Next.
-
Then, in the Assign users and
groups dialog box that opens, type and
select the name of the user or group that you want
to assign. Then select
Assign.
Search for users using their name, and not
their user ID or email alias.
-
From the Users page, After
Amazon Q Business finishes assigning the
user to your application, select the subscription
type to assign to your user from Current
subscription.
The default subscription type assigned to a
user is Q Business Pro.
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.
-
If you've created a minimally-configured IAM Identity Center
instance from within the Amazon Q Business console for your
Amazon Q Business application, you can enter the details of your
users or users within a group to add them to your
application environment and IAM Identity Center instance.
-
In this case, in the Add new
users dialog box that opens, enter the
details of your user. Then select
Next and
Add.
If you want to add another user or multiple users,
select Add new user and enter
the user details before you select
Add. Then, select
Assign.
The user is automatically added to an IAM Identity Center
directory.
-
The details you must enter for a single user
include:
-
Username – A
username is required for an 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: +=,.@-_
-
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.
-
In Web experience service access, enter the
following information:
-
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.
-
Service role name – A name for
the service role you created for easy identification on the
console.
-
Select Done.
- AWS CLI
-
To add users to an application environment (subscriptions for
users is only available in the console)
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 environment (subscriptions for
groups is only available in the console)
aws sso-admin create-application-assignment \
--application-arn idc-app-arn
\
--principal-id idc-group-ID
\
--principal-type GROUP
Step 3: Customize web experience
Creating an Amazon Q Business application automatically creates a web experience
with a shareable URL. Before you share your web experience URL, you can choose to
customize it.
You can customize a web experience by using either the AWS Management Console or the Amazon Q API. If you use the API, customizing your Amazon Q Business can
involve a combination of the following API operations:
When you customize your web experience, you can personalize it by changing its title
and subtitle, adding a welcome message, and displaying sample prompts.
You can't run any chat queries from the web experience customize mode.
The following tabs provide a procedure for the AWS Management Console and code examples for the
AWS CLI.
- Console
-
To customize an Amazon Q Business web
experience
-
Sign in to the AWS Management Console and open the Amazon Q Business console.
-
Complete the steps to create your Amazon Q Business
application.
-
Then, from the Amazon Q Business application environment page, select your application, and then select
Customize web experience.
-
In Customize web experience, from the right
navigation pane, select Customize web
experience.
-
In Customize web experience, enter the
following information for your web experience:
-
Title – A title for your web
experience. End users see this title on their web experience
page.
-
Subtitle -
optional – A
subtitle for your web experience to highlight other
information for your end users. This subtitle is visible to
your end users on their web experience page.
-
Welcome message – Provide an
optional welcome message for your end users. We recommend
mentioning data sources and application environment capabilities.
-
Display sample prompts –
Provide a list of sample prompts on the end
user's conversation start screen.
-
Choose Save.
- AWS CLI
-
To create and customize a web
experience
aws qbusiness create-web-experience \
--application-id application-id
\
--role-arn roleArn
\
--title optional-title
\
--subtitle optional-subtitle
\
--welcome-message optional-welcome-message
\
--sample-prompts-control-mode ENABLED
Managing a sample application
You can manage your sample application, including users and groups and their
subscriptions, using the AWS Management Console and the API.
To learn more about managing your sample application, see Managing Amazon Q Business applications.
To manage user subscriptions, see Managing user subscriptions.
To manage users and groups programmatically for your Amazon Q Business
application, refer to the IAM Identity Center CLI Reference and the Identity Store API Reference.