Creating an Amazon Q Business application using IAM Federation through Okta - Amazon Q Business
PrerequisitesStep 1: Create and configure an Okta applicationStep 2: Add an identity provider in IAMStep 3: Connect IAM to OktaStep 4: Create Amazon Q Business applicationStep 5: Create Amazon Q Business retrieverStep 6: Connect Amazon Q Business data sourcesStep 7: Manage access

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.

    Note

    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.

Important

Amazon Q Business doesn't support OIDC for Google and Microsoft Entra ID.

SAML

To create an Okta instance

  1. Sign into Okta and go to the admin console.

  2. In the left navigation pane, choose Applications, and then choose Create App Integration.

  3. On the Create a new app integration page, choose SAML 2.0 and then choose Next.

  4. On the Create SAML Integration page, in General Settings, for App name, enter a name for the application and choose Next.

  5. In Configure SAML, do the following:

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

      Important

      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.

    2. Uncheck the Use this for Recipient URL and Destination URL box.

    3. Then, for the Recipient URL field, enter the following AWS endpoint: https://signin.aws.amazon.com/saml.

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

    5. For Audience URI (SP Identity ID), enter the following AWS endpoint: https://signin.aws.amazon.com/saml.

    6. For Name ID format, set to Persistent.

    7. The, scroll down to the bottom of the page and select Next.

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

  7. On the application summary page, from the top navigation menu, select Assignments, and then select Assign. Then, complete the following steps:

    1. To assign users to your Okta app, choose between Assign to People and Assign to Groups.

    2. In the dialog box that opens up, locate the users or groups you want to assign to your application and then select Assign.

    3. Then, choose Done.

  8. 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:

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

      Note

      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.

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

  1. Sign into Okta and go to the admin console.

  2. In the left navigation pane, choose Applications, and then choose Create App Integration.

  3. On the Create a new app integration page, do the following:

    • Choose OIDC – OpenID Connect.

    • Choose Web application.

    • Then, choose Next.

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

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

  6. From the left navigation menu, select Security, and then select API.

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

  8. 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} }}.

      Note

      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

  1. Sign in to the AWS Identity and Access Management console.

  2. In the left navigation menu, from Access management, select Identity providers.

  3. From Identity providers, select Add provider.

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

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

  6. In Assign role, for Role options select Create a new role.

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

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

    Note

    To create a new policy, follow the instructions in Creating IAM policies in the AWS Identity and Access Management User Guide.

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

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

  1. Sign in to the AWS Identity and Access Management console.

  2. In the left navigation menu, from Access management, select Identity providers.

  3. From Identity providers, select Add provider.

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

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

  6. In the Assign role dialog box that opens , for Role options select Create a new role.

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

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

    Note

    To create a new policy, follow the instructions in Creating IAM policies in the AWS Identity and Access Management User Guide.

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

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

  11. 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": "*" 
                }
            }
        }
    ]
}

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

  1. Sign into Okta and go to the admin console.

  2. In the left navigation pane, choose Applications, and then choose the Okta application you created.

  3. In General, from SAML Settings choose Edit.

  4. In Edit SAML, for General Settings choose Next.

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

      Note

      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

  1. Sign in to the AWS Management Console and open the Amazon Q Business console.

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

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

      Note

      For more information about example service roles, see IAM role for an Amazon Q Business application. For information on service-linked roles, including to manage them, see Using service-linked roles.

    • Service role name – A name for the service (IAM) role you created for easy identification on the console.

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

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

  6. 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:

    • Key – Add a key for your tag.

    • Value - optional – An optional value for your tag.

    For more information about using tags with Amazon Q Business, see Tags.

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

Important

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.

Note

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

  1. Sign in to the AWS Management Console and open the Amazon Q Business console.

  2. Complete the steps to create your Amazon Q Business application.

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

    Note

    Available data sources when you select this option include all Amazon Q Business supported data connectors and direct document upload.

  4. In Index provisioning, do the following:

    1. Choose between Starter and Enterprise index types based on your use case. For more information on index types, see Index types.

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

  5. For Tags – Choose whether you want to add Index tags.

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

Note

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

  1. Sign in to the AWS Management Console and open the Amazon Q Business console.

  2. Complete the steps to create your Amazon Q Business application.

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

  4. In Tags – Choose whether you want to add Retriever tags.

  5. 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:

  • Connect to any Amazon Q Business supported data source connectors by using the CreateDataSource API operation.

  • Upload documents directly by using the BatchPutDocument API operation.

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

Note

This procedure is available if you chose the Use native retriever option to configure your application environment.

  1. Sign in to the AWS Management Console and open the Amazon Q Business console.

  2. Complete the steps to create your Amazon Q Business application.

  3. Complete the steps for selecting an Amazon Q Business retriever.

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

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

Note

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.

Note

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

  1. Sign in to the AWS Management Console and open the Amazon Q Business console.

  2. Complete the steps to create your Amazon Q Business application.

  3. Complete the steps for selecting an Amazon Kendra retriever.

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

  5. 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>}"
Note

For information on managing your Amazon Kendra retriever, see Managing Amazon Kendra retrievers.

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.

Note

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

  1. Sign in to the AWS Management Console and open the Amazon Q Business console.

  2. Complete the steps to create your Amazon Q Business application.

  3. Complete the steps for selecting an Amazon Q Business retriever.

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

  5. For information on configuring your chosen data source, see Supported connectors to find configuration information specific to your data source.

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

Warning

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

  1. Sign in to the AWS Management Console and open the Amazon Q Business console.

  2. Complete the steps to create your Amazon Q Business application.

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

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

      Note

      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.

  5. Select Create application.

OIDC

To manage user access

  1. Sign in to the AWS Management Console and open the Amazon Q Business console.

  2. Complete the steps to create your Amazon Q Business application.

  3. On the Manage access, for Default subscription settings, for Subcription tier, choose between Q Business Pro and Q Business Lite.

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

      Note

      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.

      Note

      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.

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