Creating an Amazon Q Business
application using IAM Federation through Okta
As the first step towards creating a generative artificial intelligence (AI)
assistant, you configure your external identity provider and connect it to AWS Identity and Access Management.
Then, you create an application environment, select and create a retriever, and also connect any
data sources. After this, you deploy your web experience and provision subscriptions for
end users to log in to a web experience.
Your authorized users interact with your application environment through the web experience. You
can share the web experience URL generated by Amazon Q Business with your users,
who open the URL and are authenticated before they can start asking questions in your
assistant application environment. The endpoint URL can be found in your web experience settings
when selecting your application environment in the console.
To learn more about identity federation using AWS Identity and Access Management, see the following
topics:
The following steps show how to integrate Amazon Q Business with
Okta as an example. Integrating Amazon Q Business with
Okta requires that you switch between tasks on the Amazon Q Business console and the Okta admin console.
Prerequisites
Before you start to integrate Amazon Q Business with Okta,
make sure that you have:
-
Created an Okta account and added at least one user with a
valid email address. For more information, see Manage users on the Okta Help
Center.
-
Created IAM policies containing the permissions outlined in IAM role for an Amazon Q Business web
experience using IAM Federation to:
-
Allow an Amazon Q Business web experience to invoke the API
operations required to integrate your application
-
(If you're creating a Amazon Q Business default web
experience) Allow Amazon Q Business to access the resources it
needs to create a web experience
-
(If you're using OIDC) Allow an Amazon Q Business web
experience to invoke the API operations required to decrypt the
Secrets Manager secret you created for your OIDC web experience
You will need these roles to complete creating your Amazon Q Business IAM-federated application.
To create a new policy, follow the instructions in Creating
IAM policies in the AWS Identity and Access Management User Guide.
-
(Optional) Checked how subscriptions work for Amazon Q Business applications using IAM Federation.
Step 1: Create and configure an
Okta application
This procedure outlines how to create and configure an Okta
instance for an Amazon Q Business application using a built-in web experienc
and a custom Amazon Q Business application client you develop using Amazon Q Business APIs.
Amazon Q Business doesn't support OIDC for Google and
Microsoft Entra ID.
- SAML
-
To create an Okta instance
-
Sign into Okta and go to the admin
console.
-
In the left navigation pane, choose
Applications, and then choose
Create App Integration.
-
On the Create a new app integration page,
choose SAML 2.0 and then choose
Next.
-
On the Create SAML Integration page, in
General Settings, for App
name, enter a name for the application and choose
Next.
-
In Configure SAML, do the
following:
-
For Single sign-on URL, enter
your web application endpoint.
If you're creating a custom Amazon Q Business
application, this value is the endpoint URL of your
Amazon Q Business application with
/saml
added at the end. For example
http://localhost:8000/saml
.
If you're creating an Amazon Q Business
application generated web experience endpoint URL, this
value be the Amazon Q Business generated web
experience URL with saml
added at the end.
For example,
https://abcdefgh.qbusiness.us-east-1.on.aws/saml
.
If you're creating an Amazon Q Business
application generated web experience endpoint URL, a
web experience URL will be generated by Amazon Q Business after you finish creating an
Amazon Q Business application. For now,
enter a placeholder URL. For example:
http://sampleurl.com
.
You will update this at the end of your Amazon Q Business application creation
process.
-
Uncheck the Use this for Recipient URL and
Destination URL box.
-
Then, for the Recipient URL
field, enter the following AWS endpoint:
https://signin.aws.amazon.com/saml
.
-
For Destination URL, enter your
web application endpoint.
If you're creating a custom Amazon Q Business
application, this value is the endpoint URL of your
Amazon Q Business application with
/saml
added at the end. For example
http://localhost:8000/saml
.
If you're creating an Amazon Q Business
application generated web experience endpoint URL, this
value be the Amazon Q Business generated web
experience URL with saml
added at the end.
For example,
https://abcdefgh.qbusiness.us-east-1.on.aws/saml
.
If you're creating an Amazon Q Business
application generated web experience endpoint URL, a web
experience URL will be generated by Amazon Q Business after you finish creating an Amazon Q Business application. For now, enter a
placeholder URL. For example:
http://sampleurl.com
. You
will update this at the end of your Amazon Q Business application creation process.
-
For Audience URI (SP Identity
ID), enter the following AWS endpoint:
https://signin.aws.amazon.com/saml
.
-
For Name ID format, set to
Persistent.
-
The, scroll down to the bottom of the page and select
Next.
-
On the Create SAML Integration page, select the
option that best fits your use case and then select
Finish. You will be redirected to the
application summary page.
-
On the application summary page, from the top navigation menu,
select Assignments, and then select
Assign. Then, complete the following
steps:
-
To assign users to your Okta app,
choose between Assign to People and
Assign to Groups.
-
In the dialog box that opens up, locate the users or
groups you want to assign to your application and then
select Assign.
-
Then, choose Done.
-
Next, you download the SAML payload and copy your
Sign on URL.
You need to provide the SAML payload when you create an
identity provider in IAM.
If you choose to create a web experience from the Amazon Q Business console (Step 7 of this page), you input the
Sign on URL or Single Sign-On
URL (the URL where users sign in to access an
application integrated with an identity provider) as the
Authentication URL. The standard
authentication URL format for Okta is:
https://<sub_domain>.okta.com/app/<app_name>/<app_id>/sso/saml
.
From the top navigation menu of your application home page,
select Sign On. Then, complete the
following steps:
-
In the Settings, from the
SAML 2.0 section, from
Metadata details section, to
copy the metadata file XML file by choosing
Copy. Then, save it in
.xml
format.
You can also navigate to the metadata URL and copy
the network response payload and paste it in a file
that you save in .xml
format.
For more information, see Create SAML app integrations on the
Okta Help
Center website.
-
Then, from Sign on URL, select
the Copy icon to copy the Sign on
URL. Save it in a text editor of your choice.
- OIDC
-
To create an Okta instance
-
Sign into Okta and go to the admin
console.
-
In the left navigation pane, choose
Applications, and then choose
Create App Integration.
-
On the Create a new app integration page,
do the following:
-
On the New Web App Integration page, do
the following:
-
In General Settings, for
App name, enter a name for the
application.
-
In Grant type, for Core
grants, ensure that
Authorization Code is
selected.
-
In Sign-in-redirect URIs, add a
URL that Okta will send the
authentication response and ID token for the user's sign
in request.
If you're using a custom application, the value of
this URL will be
http://localhost:8080/authorization-code/callback
,
where http://localhost:8080
is your custom
web experience endpoint URL.
If you're creating an Amazon Q Business
application generated web experience endpoint URL, this
value will be the Amazon Q Business generated web
experience URL with
/authorization-code/callback
added at
the end. Amazon Q Business generates this web
experience URL when you create a Amazon Q Business
application using in Step 7. For now, enter a
placeholder URL. For example:
http://sampleurl.com/authorization-code/callback
.
You will update this after you finish creating a Amazon Q Business application by inputting your
Amazon Q Business web experience URL with
/authorization-code/callback
added at
the end. For example,
https://abcdefgh.qbusiness.us-east-1.on.aws/authorization-code/callback
.
-
In Assignments, select whether to
assign the app integration to everyone in your org, only
selected group(s), or skip assignment until after app
creation.
-
Then, select Save.
-
From the application summary page, from
General, do the following:
-
From Client Credentials, copy and
save the Client ID. You will input
this as the Audience when you
create an identity provider in AWS Identity and Access Management in the next
step.
-
From CLIENT SECRETS, copy and
save the Secret. If you choose to
use an Amazon Q Business default web experience,
you will need to input this in an Secrets Manager secret when you
configure Web experience settings
in the Amazon Q Business console.
-
From the left navigation menu, select
Security, and then select
API.
-
Then, from Authorization Servers, do the
following:
-
Copy the Issuer URI, for example
https://trial-okta-instance-id
.okta.com/oauth2/default
.
You will need to input this value as the
Provider URL when you add your
identity provider in IAM in Step 2.
-
Select default, and then select
Claims.
-
In Claims, select Add
claim, and then do the following:
-
For Name, add
https://aws.amazon.com/tags
.
-
For Include in token type, choose
ID token
and select
Always.
-
For Value, add the following:
{"principal_tags": {"Email": {user.email}
}}
.
To activate Amazon Q Business
response personalization for your
application, add the following optional tags:
{"principal_tags": {"Email": {user.email},
"country": {user.city != null ? user.city :
""}}}
. Ensure that null values aren't
passed via principal tags by using the operation
user.$attribute != null ? user.$attribute :
""
.
-
For Include in, choose Any
scope
.
-
Select Create.
You are now ready to go to the AWS Identity and Access Management console and create an OIDC
identity provider instance.
You are now ready to move to the AWS Identity and Access Management console to create an identity provider
integration for your Okta instance.
Step 2: Add an identity provider in
IAM
In this step, you add configure AWS Identity and Access Management by creating an identity provider
integration for your Okta instance.
- SAML
-
To connect Okta to AWS Identity and Access Management
-
Sign in to the AWS Identity and Access Management console.
-
In the left navigation menu, from Access
management, select Identity
providers.
-
From Identity providers, select
Add provider.
-
In Add an identity provider, for
Configure provider do the
following:
-
For Provider type – Select
SAML.
-
For Provider name – Add a
name to identify your identity provider.
-
For Metadata document –
Upload the .xml
file you downloaded and
saved from Okta in Step 1.
-
For Add tags -
optional –
Add tags to resources to help identify, organize, or
search for the identity provider you're adding.
-
Select Add provider.
-
On the Identity provider summary page,
from Provider, select the provider you just
added do the following:
-
From Summary copy the
ARN and save the value. You
will need it when you add your trust policy and when you
connect your AWS Identity and Access Management identity provider to your
Okta instance. The format of the ARN
is:
arn:aws:iam::aws-account-id
:saml-provider/assigned-iam-idp-name
.
-
Then, select Assign role to
create an IAM role with the necessary permissions for
your identity provider.
-
In Assign role, for Role
options select Create a new
role.
-
Then, on the Selected trusted entity
page, do the following:
-
For Trusted entity type select
SAML 2.0 federation.
-
In SAML 2.0 federation, from the
SAML 2.0-based provider
dropdown, select the identity provider you added.
-
For Access to be allowed, select
Allow programmatic access
only.
-
For Attribute, select
SAML:aud.
-
For Value, enter the following:
https://signin.aws.amazon.com/saml
.
-
Select Next.
-
On the Add permissions page, for
Permissions policies choose an IAM
policy with the required permissions and then select
Next.
For the policy permissions required, see IAM role for an Amazon Q Business web experience using IAM Federation.
To create a new policy, follow the instructions in Creating IAM policies in the AWS Identity and Access Management User
Guide.
-
In the Name, review, and create page, add
a Role name, and optional role description
and tags to identify your IAM role. Then, select
Create role.
-
From the Roles page, select the IAM
role you just created. Then, from the role summary page, do the
following:
-
Copy the role ARN and save it.
You will need this information to connect your AWS Identity and Access Management
identity provider instance to Okta. The
format of the ARN will be like this:
arn:aws:iam::111122223333:role/sample-role
.
-
In Trust relationships, select
Edit trust policy and select
Add new statement to add the
following trust policy, replacing the value for
account_id
with your
AWS account ID and
saml_provider
with the
assigned-iam-idp-name
you
copied from your IAM identity provider ARN you
copied:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Federated": "arn:aws:iam::{{account_id
}}:saml-provider/[[saml_provider
]]"
},
"Action": "sts:AssumeRoleWithSAML",
"Condition": {
"StringEquals": {
"SAML:aud": "https://signin.aws.amazon.com/saml"
}
}
},
{
"Effect": "Allow",
"Principal": {
"Federated": "arn:aws:iam::{{account_id
}}:saml-provider/[[saml_provider
]]"
},
"Action": "sts:TagSession",
"Condition": {
"StringLike": {
"aws:RequestTag/Email": "*"
}
}
}
]
}
-
Then, select Update
policy.
You are now ready to return to Okta to complete the
process of extablishing a trust relationship between AWS Identity and Access Management and
Okta.
- OIDC
-
To connect Okta to AWS Identity and Access Management
-
Sign in to the AWS Identity and Access Management console.
-
In the left navigation menu, from Access
management, select Identity
providers.
-
From Identity providers, select
Add provider.
-
In Add an identity provider, for
Configure provider do the
following:
-
For Provider type – Select
OpenID Connect.
-
For Provider URL – Paste
the Input URI you copied from the
Okta console. For example,
trial-okta-instance-id
.okta.com/oauth2/default
.
-
For Audience – Copy and
paste the Client ID you copied from Okta
from the Okta console.
-
For Add tags -
optional –
Add tags to resources to help identify, organize, or
search for the identity provider you're adding.
-
Select Add provider.
-
On the Identity provider summary page,
from Provider, select the provider you
added do the following:
-
From Summary copy the
ARN and save the value. You
will need it when you add your trust policy and when you
connect your AWS Identity and Access Management identity provider to your
Okta instance. The format of the ARN
is:
arn:aws:iam::aws-account-id
:oidc-provider/issuer
.
-
Then, select Assign role to
create an IAM role with the necessary permissions for
your identity provider.
-
In the Assign role dialog box that opens
, for Role options select Create
a new role.
-
Then, on the Selected trusted entity
page, do the following:
-
For Trusted entity type select
Web identity.
-
In Web identity, from the
Identity provider dropdown,
select the identity provider you added.
-
For Audience, select your Client
ID.
-
Select Next.
-
On the Add permissions page, for
Permissions policies choose an IAM
policy to add, and then select Next. You
can add an existing policy or update your policy you're creating
to include required permissions. Your policy must contain the
permissions outlined in IAM role for an Amazon Q Business web experience using IAM Federation.
To create a new policy, follow the instructions in Creating IAM policies in the AWS Identity and Access Management User
Guide.
-
In the Name, review, and create page, add
a Role name add a role name, and optional
role description and tags to identify your IAM role. Then,
select Create role.
-
From the Roles page find and select the
IAM role you created. Then, from the role summary page, in
Trust relationships, select
Edit trust policy and select
Add new statement
-
Then, add the following statement to your existing trust
policy, replacing account-id
with
your AWS account ID, clientId
with
the OIDC client ID you copied, and
iss
with the
issuer
value from your IAM
identity provider ARN:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Federated": "arn:aws:iam::{{account_id
}}:oidc-provider/{{iss
}}"
},
"Action": "sts:AssumeRoleWithWebIdentity",
"Condition": {
"StringEquals": {
"{{iss
}}:aud": "{{clientId
}}"
}
}
},
{
"Effect": "Allow",
"Principal": {
"Federated": "arn:aws:iam::{{account_id
}}:oidc-provider/{{iss
}}"
},
"Action": "sts:TagSession",
"Condition": {
"StringLike": {
"aws:RequestTag/Email": "*"
}
}
}
]
}
-
Then, select Update policy.
Now, move on to the Amazon Q Business console to create your
application.
Step 3: Connect IAM to
Okta
In this step, you complete configuring the trust relationship between AWS Identity and Access Management
and Okta.
- SAML
-
-
Sign into Okta and go to the admin
console.
-
In the left navigation pane, choose
Applications, and then choose the
Okta application you created.
-
In General, from SAML
Settings choose Edit.
-
In Edit SAML, for General
Settings choose Next.
-
In Configure SAML, scroll down to the
Attribute Statements section, and add
the following attributes:
Attribute 1
-
For the Name field, provide the
following for the email attribute:
https://aws.amazon.com/SAML/Attributes/PrincipalTag:Email
.
-
For the Name format field, keep
it set to Unspecified.
-
For the Value field, provide a
mapping to the attribute by selecting
user.email
from the dropdown
list.
You can add more attributes to enable Amazon Q Business
response personalization. To do this,
provide the following value for the
Name field:
https://aws.amazon.com/SAML/Attributes/PrincipalTag:<attributeName>
.
Keep the Name format field
Unspecified. For
Value, provide an attribute
mapping by selecting a user attribute like
user.city
from the dropdown
list.
Attribute 2
-
For the Name field, provide the
following name for the role attribute:
https://aws.amazon.com/SAML/Attributes/Role
.
-
For the Name format field, keep
it set to Unspecified.
-
For the Value field, add a
mapping to the attribute in the following format using
the values you copied from Step 2 of this section:
IAMroleArn,IAMidpArn
. For example:
arn:aws:iam::111122223333:role/sample-role,arn:aws:iam::111122223333:saml-provider/okta-idp
.
Attribute 3
-
Then, for the Name field, provide
the following name for the role session name attribute:
https://aws.amazon.com/SAML/Attributes/RoleSessionName
.
-
For the Name format field, keep
it set to Unspecified.
-
For the Value field, provide a
mapping to the attribute by selecting
user.email
from the dropdown
list.
-
Choose Next, and then choose
Finish.
Now, move on to the Amazon Q Business console to create your
application.
- OIDC
-
This step isn't needed for
OIDC.
Step 4: Create Amazon Q Business
application
To create an Amazon Q Business application environment, you can use either the
AWS Management Console or the Amazon Q Business API.
As a prerequisite, make sure that you complete the setting
up tasks. If you're using the AWS CLI or the API, make sure that you
created the required IAM roles.
After you create an application environment, you can create your Amazon Q Business web
experience. How you create the web experience depends on whether you use the
AWS Management Console or the Amazon Q Business APIs.
-
AWS Management Console – If you use the console
to create an application environment, the web experience is created
automatically.
-
Amazon Q Business API – If
you use the CreateApplication API
operation to create an application environment, use the CreateWebExperience API
operation to create your web experience.
The following tabs provide a procedure for creating your Amazon Q Business
application environment using the AWS Management Console and code examples for using the AWS CLI.
- Console
-
To create an application
-
Sign in to the AWS Management Console and open the Amazon Q Business
console.
-
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
AWS Identity and Access Management Identity Provider, and then
do the following:
-
For Choose an Identity Provider
type, choose either
SAML or OpenID
Connect.
-
For Select Identity Provider,
choose the identity provider you've created in AWS Identity and Access Management
to use with your Amazon Q Business
application.
-
If you're using OIDC, also do
the following:
For ClientID for OIDC, input the
OIDC client ID you copied in Step
1.
-
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 \
--iam-identity-provider-arn iam-identity-provider-arn \
--client-id-for-oidc client-id-for-oidc \
--identity-type identity-type\
--role-arn roleArn \
--description application-description \
--enryption-configuration kmsKeyId=<kms-key-id> \
--attachments-configuration attachmentsControlMode=ENABLED
Step 5: Create Amazon Q Business
retriever
After creating your Amazon Q Business application environment, you create and select
the retriever and provision the index that will power your generative AI web
experience. The retriever pulls data from the index in real time during a
conversation.
Amazon Q Business provides retrievers for Amazon Kendra indexes and
also for a native index. You can choose between selecting an Amazon Q Business
retriever and a Amazon Q Business native index or using an already configured
Amazon Kendra index as a retriever.
To select a retriever, you use the AWS Management Console or the CreateRetriever API operation. If you use the console and choose to use
a Amazon Q Business retriever, Amazon Q Business creates an index for
you as part of the application environment configuration process. You can then configure
provisioning for the created index.
For easy tracking, you can tag both the retriever and index. If you use the API to
create a Amazon Q Business retriever, you must first use the CreateIndex API operation to create and provision an
Amazon Q Business index, and then use CreateRetriever to create your Amazon Q retriever.
You can't change the retriever or index type for your application environment after your
application environment has been created. To change your retriever or index type, you must
create a new application environment.
The data sources and indexes available to connect to your application environment change
depending on your retriever choice.
For instructions on how to select a retriever and an
index, choose a topic based on your retriever preference for Amazon Q:
To select a Amazon Q Business retriever, you can use either the
AWS Management Console, or the CreateIndex and CreateRetriever API operations.
The following tabs provide a procedure for the AWS Management Console and code examples
for the AWS CLI.
- Console
-
To create an Amazon Q Business
retriever
-
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, for Select retriever,
choose Use native retriever
– Build an Amazon Q Business retriever for
your Amazon Q Business application environment. This option
creates an Amazon Q Business index that can
connect to the Amazon Q Business supported data
sources that you choose.
-
In Index provisioning, do the
following:
-
Choose between Starter
and Enterprise index types
based on your use case. For more information on
index types, see Index types.
-
For Number of units
– Choose the Number of
units that you need. Amazon Q Business charges you based on the document
capacity that you choose. If you choose an
Enterprise index, You can choose up to 50 units.
If you choose a Starter index, you can choose up
to 5 units. Each unit is 20,000 documents or 200
MB, whichever is reached first. For more
information on index provisioning pricing, see
Amazon Q Business pricing.
-
For Tags – Choose whether
you want to add Index tags.
-
To create your retriever and index, choose
Create.
- AWS CLI
-
To create an Amazon Q Business
index
aws qbusiness create-index \
--application-id application-id
\
--display-name display-name
\
--description index-description
\
--capacity-configuration units =<index-capacity-units>
\
--type ENTERPRISE | STARTER
To create an Amazon Q Business
retriever
aws qbusiness create-retriever \
--application-id application-id
\
--display-name display-name
\
--type NATIVE_INDEX
\
--role-arn roleArn
\
--configuration nativeIndexConfiguration="{indexId=<created-index-id>}" \
--tags tags
To select an existing Amazon Kendra retriever to your Amazon Q Business application environment, you can use the AWS Management Console or the CreateRetriever API
operation.
If you use the API, you select and connect your Amazon Kendra
retriever when you use the CreateRetriever
API
operation.
If you use the console, selecting and connecting an Amazon Kendra
retriever is a two-step process. This topic provides instructions for the
first step: Selecting an Amazon Kendra retriever. For instructions for
the second step, see Connecting an Amazon Kendra retriever to an Amazon Q Business
application.
If you use an Amazon Kendra retriever, data in your Amazon Kendra will be connected to your Amazon Q Business
application environment. If you choose this option, you can't use Amazon Q Business data connectors or direct document upload for your
application environment.
For more information about Amazon Kendra, see the following topics in
the Amazon Kendra User Guide and API Reference:
The following tabs provide a procedure for the AWS Management Console and code samples
for the AWS CLI.
- Console
-
To create an Amazon Kendra
retriever
-
Sign in to the AWS Management Console and open the Amazon Q Business console.
-
Complete the steps to create your Amazon Q Business application.
-
The, in Select retriever choose
Use existing retriever –
Choose an Amazon Kendra index you have previously
created as a retriever. All data sources synced to your
Amazon Kendra index will be connected to your
Amazon Q Business application environment.
-
In Tags – Choose whether
you want to add Retriever
tags.
-
To connect your application environmentto your data sources,
choose Next.
- AWS CLI
-
To create an Amazon Kendra
retriever
aws qbusiness create-retriever \
--display-name display-name
\
--type KENDRA_INDEX
\
--role-arn roleArn
\
--configuration kendraIndexConfiguration="{indexId=<kendra-index-id>
Step 6: Connect Amazon Q Business
data sources
After you select a retriever for your Amazon Q Business application environment, you
connect data sources to it. Available data sources vary based on your choice of the
retriever.
If you use an Amazon Q Business retriever, you can choose from the following
options:
If you use an existing Amazon Kendra retriever, only data sources already
connected to your Amazon Kendra index are available in your
application environment.
To connect data sources, choose a topic based on
your data source preference for your Amazon Q Business application environment:
To upload documents directly to an Amazon Q Business application environment,
you can use the AWS Management Console or the BatchPutDocument API
operation.
If you use an Amazon Kendra index to retrieve your documents, you
can't directly upload documents.
The following tabs provide a procedure for the AWS Management Console and code examples
for the AWS CLI.
- Console
-
To upload documents
This procedure is available if you chose the Use
native retriever option to configure your
application environment.
-
Sign in to the AWS Management Console and open the Amazon Q Business console.
-
Complete the steps to create your Amazon Q Business application.
-
Complete the steps for selecting an Amazon Q Business retriever.
-
Then, for Upload documents,
select one of the following methods to add your
files:
-
Drag and drop the document files that you want
to upload.
-
Add your documents to the application environment, and
then select Choose
files.
-
After choosing your files, choose
Upload.
You are returned to the Amazon Q Business
console while your documents are uploaded. The console
displays a confirmation message when your documents are
successfully uploaded.
Files can only be uploaded after the Amazon Q Business retriever and index creation process has
completed.
- AWS CLI
-
To upload documents
directly
aws qbusiness batch-put-document \
--application-id application-id
\
--index-id index-id
\
--documents documents-to-add
\
--data-source-sync-id data-source-sync-id
\
--role-arn roleArn
To use an Amazon Kendra index as a retriever for Amazon Q Business, you must have already configured an Amazon Kendra
index and connected it with data. For more information, see What is
Amazon Kendra? and Are you a first-time Amazon Kendra
user? in the Amazon Kendra Developer Guide.
To add an existing Amazon Kendra retriever to your Amazon Q Business
application environment, you can use the AWS Management Console or the CreateRetriever API
operation. If you use the console, selecting and connecting an Amazon Kendra retriever is a two-step process. The first step is when you
select an Amazon Kendra retriever. In
this topic, you perform the second step—connecting an Amazon Kendra retriever.
If you use the API, you create your web experience after connecting your
Amazon Kendra retriever using the CreateWebExperience API
operation. If you use the console, connecting your Amazon Kendra
retriever also automatically creates your Amazon Q Business web
experience. At the end of the retriever connection process, your Amazon Kendra powered Amazon Q Business web experience is ready to be
previewed, enhanced, and deployed.
If you select an Amazon Kendra retriever, data in your Amazon Kendra is connected to your Amazon Q Business
application environment.
- Console
-
To connect an Amazon Kendra
retriever
-
Sign in to the AWS Management Console and open the Amazon Q Business console.
-
Complete the steps to create your Amazon Q Business application.
-
Complete the steps for selecting an Amazon Kendra
retriever.
-
Then, in Content sources, for
Amazon Kendra indexes
– Choose the Amazon Kendra index that you
want to use for your Amazon Q Business
application environment. Then, enter the following
information:
-
Service access –
Provide the IAM access role to
connect Amazon Kendra to Amazon Q Business. Use an existing role, or create a
new one.
-
Service role name
– Provide a name for your IAM access role. Or, choose to use the
auto-generated role that's provided.
-
To connect your Amazon Kendra indexes to the
application environment, choose Create
application.
You are returned to the Amazon Q Business console while
your web application environmentis created.
- AWS CLI
-
To create and connect an Amazon Kendra retriever
aws qbusiness create-retriever \
--application-id application-id
\
--display-name display-name
\
--type KENDRA_INDEX
\
--role-arn roleArn
\
--configuration kendraIndexConfiguration="{indexId=<kendra-index-id>}"
To connect a data source to your Amazon Q Business application environment,
you can use the AWS Management Console or the CreateDataSource API
operation.
By using the CreateDataSource
API operation, you can
configure tags, sync run schedules, and configure Amazon VPC
settings. Then, you can use the configuration
parameter to
provide all other configuration information specific to your data source
connector.
If you use the console, creating the data source and configuring it are a
single step. After your data source is successfully configured and added,
Amazon Q automatically creates a Amazon Q Business web
experience for you.
If you use the API, you use the CreateWebExperience API
operation after connecting your data sources to create your web
experience.
This procedure is available if you chose the Use native
retriever option to configure your
application environment.
- Console
-
To connect a data source to an Amazon Q application
-
Sign in to the AWS Management Console and open the Amazon Q Business console.
-
Complete the steps to create your Amazon Q Business application.
-
Complete the steps for selecting an Amazon Q Business retriever.
-
Then, from Data sources –
Add an available data source to connect your Amazon Q Business application environment.
You can add up to 50 data sources.
-
For information on configuring your chosen data
source, see Supported connectors to
find configuration information specific to your data
source.
-
To connect your configured data source to your
application environment, choose Add data
sources.
At the end of this step, your Amazon Q Business web
experience is ready to be previewed, enhanced, and
deployed.
- AWS CLI
-
To connect a data
source
aws qbusiness create-data-source \
--application-id application-id
\
--index-id index-id
\
--configuration data-source-configuration-details
\
--display-name display-name
\
--role-arn roleArn
\
--description description
\
--document-enrichment-configuration document-enrichment-configuration
\
--sync-schedule sync-schedule-information
\
--tags tags
\
--vpc-configuration vpc-configuration
Step 7: Manage
access
In this step, you add subscriptions for end users logging into your Amazon Q Business web experience using Okta and configure your
Amazon Q Business web experience. Any user logging into your web
experience is automatically provisioned a subscription of the type you
select.
If you're using an Amazon Q Business default web experience for your
application, you can choose to generate it in this step. If you're using this
generated URL as your web experience endpoint, you need to return to
Okta to update your identity provider instance with this
information.
User subscriptions are connected to the AWS account Amazon Q Business
applications are attached to. If the same user logs in to an Amazon Q Business application using multiple AWS accounts, they're charged
multiple times. Create an Amazon Q Business application using
IAM Identity Center for user management to avoid this issue.
For a consolidated view of all your user
subscriptions see the Amazon Q subscriptions
page. Subscriptions can only be viewed centrally and
not be created or updated from the Amazon Q
subscription management console.
For more information on user subscriptions for an IAM federated Amazon Q Business application, see Subscriptions for applications using IAM
Federation.
- SAML
-
To manage user acess
-
Sign in to the AWS Management Console and open the Amazon Q Business
console.
-
Complete the steps to create your Amazon Q Business
application.
-
On the Manage access, for
Default subscription settings, for
Subcription tier, choose between
Q Business Pro and Q Business
Lite. Any user logging in to your web experience
will be assigned this subscription type by default.
-
(Optional) If you're using an
Amazon Q Business default web experience for your
application, for Create web experience,
select to create an Amazon Q Business web experience with
a shareable URL. Then, in Web experience
settings, do the following:
-
In Choose a method to authorize Amazon Q Business, choose an existing
IAM role to allow your Amazon Q Business web experience to access the AWS resources it needs to function.
For the policy permissions required, see IAM role for an Amazon Q Business web experience using IAM
Federation.
To create a new policy, follow the instructions in
Creating IAM policies in the AWS Identity and Access Management
User Guide.
-
For Service role name, choose an
existing role you want to use form the dropdown
options.
-
In Provide Authentication URL,
provide the authentication URL for Okta.
Your authentication URL must be of the following format:
https://<sub_domain>
.okta.com/app/<app_name>
/<app_id>
/sso/saml
.
Enter the Sign on URL you copied in
Step 1.
When end users navigate to the web experience URL
they're redirected to this authentication URL where they
provide their login ID and password. After successful
authentication, they're redirected back to the web
experience URL to begin chatting.
-
Then, select Done.
Once the application creation process completes, the web
experience settings section on your application summary page
will display your Amazon Q Business web experience URL.
Copy the URL to a file, add /saml
at the end.
Return to the Okta console, edit your
SAML application to update Single
sign-on URL and Destination
URL you added in Step 1 to your web experience
URL. Remember to save your changes.
-
Select Create application.
- OIDC
-
To manage user access
-
Sign in to the AWS Management Console and open the Amazon Q Business
console.
-
Complete the steps to create your Amazon Q Business
application.
-
On the Manage access, for
Default subscription settings, for
Subcription tier, choose between
Q Business Pro and Q Business
Lite.
-
(Optional) If you're using an
Amazon Q Business default web experience for your
application, for Create web experience,
select to create an Amazon Q Business web experience with
a shareable URL. Then, in Web experience
settings, do the following:
-
In Choose a method to authorize Amazon Q Business, choose an existing
IAM role to allow your Amazon Q Business web experience to access the AWS resources it needs to decrypt the Secrets Manager
secret you added.
For the policy permissions required, see IAM role for an Amazon Q Business web experience using IAM
Federation.
To create a new policy, follow the instructions in
Creating IAM policies in the AWS Identity and Access Management
User Guide.
-
For Service role name, choose an
existing role you want to use form the dropdown
options.
-
In AWS Secrets Manager, choose to create a
new Secrets Manager secret or add an existing one to allow Amazon Q Business to access your Okta
instance. Your secret must contain the client secret you
copied from your Okta instance.
-
In Web experience to use Secrets,
for Service role name, choose an
existing IAM role to allow your Amazon Q Business web experience to access the AWS resources it needs to function.
For the policy permissions required, see IAM role for an Amazon Q Business web experience using IAM
Federation.
To create a new policy, follow the instructions in
Creating IAM policies in the AWS Identity and Access Management
User Guide.
-
Then, select Done.
After you've done this, any end user you've added to
Okta can log in through your Amazon Q Business web experience to chat.
Once the application creation process completes, the web
experience settings section on your application summary page
will display your Amazon Q Business web experience URL.
Copy the URL to a file, add
/authorization-code/callback
at the end. Then,
return to the Okta console to edit your
OIDC application and update the
Sign-in-redirect URI value you added in
Step 1. Remember to save your changes.
-
Select Create application.
You've finished configuring your Amazon Q Business application. Your
authenticated end users can now log in and chat with your web experience.