Creating an Amazon Q Business application - Amazon Q Business

Amazon Q is in preview release and is subject to change.

Creating an Amazon Q Business application

To create an Amazon Q Business application, you can use either the AWS Management Console or the Amazon Q API.

Before you begin to create an Amazon Q application, make sure that you complete the setting up tasks. If you're using the AWS CLI or the Amazon Q API, make sure that you created the required IAM roles.

After you create an application, you can create your Amazon Q web experience. How you create the web experience depends on whether you use the AWS Management Console or the Amazon Q APIs.

  • AWS Management Console – If you use the console to create an application, the web experience is created automatically.

  • Amazon Q API – If you use the CreateApplication API operation to create an application, use the CreateWebExperience API operation to create your web experience.

The steps to create an Amazon Q application depend on whether you use IAM Identity Center as the user access manager for your Amazon Q application, or choose to use an external identity provider to manage user access.

The following sections provide procedures for creating an application using both IAM Identity Center and an external IdP.

Creating an Amazon Q Business application (IAM Identity Center)

The following tabs provide a procedure for using IAM Identity Center as the user access manager for your Amazon Q application using the AWS Management Console and code examples for using the AWS CLI.

This includes instances when you choose to manage user access to your Amazon Q application using an external identity provider IdP as an identity source through IAM Identity Center.

Important

Your Amazon Q application must be created in the same region as your IAM Identity Center instance.

Console

To configure an Amazon Q application

  1. Sign in to the AWS Management Console and open the Amazon Q console at https://console.aws.amazon.com/amazonq/.

  2. For Create Amazon Q application, choose Get started.

  3. For Applications, choose Create application. The console will display a Select access management method for application dialog box.

  4. In Select access management method for application, choose IAM Identity Center (Recommended), and then select Ok. Choosing this option allows you to use IAM Identity Center as your AWS gateway to the identoty provider of your choice.

  5. For Application settings, enter the following information for your Amazon Q application:

    • Application name – A name for your Amazon Q Business application 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.

    • Service access – An IAM role for Amazon Q Business to allow it to access the AWS resources it needs to create your application. You can choose to use an existing role or create a new role.

      Note

      For more information about example service roles, see IAM role for an Amazon Q Business application.

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

    • Encryption – Amazon Q 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. To learn more, see Data encryption.

      Important

      If you choose to use a customer managed key, you must provision at least 10 index storage units when you create an Amazon Q retriever.

  6. In Connect Amazon Q 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.

    1. If you don't have an IAM Identity Center instance configured, you see the following:

      • The region your Amazon Q application is in. This is so you can make sure that the region for your Amazon Q aplication and IAM Identity Center instance match.

      • Specify tags for IAM Identity Center – Add tags to keep track of your IAM Identity Center instance.

      • Create IAM Identity Center – Select to create a minimally-configured IAM Identity Center instance. The console will display an ARN for your newly created resource after it's created.

        Note

        If you plan to connect your IAM Identity Center to an Active Directory or external identity provider we recommend cancelling this setup and configuring IAM Identity Center from the IAM Identity Center console. If you're managing users and groups in one identity source, changing to a different identity source might remove all user and group assignments.

        If you plan to add groups to your application using your minimally-configured IAM Identity Center instance, we recommend configuring these groups in IAM Identity Center before you create your application. If you don't have already configured IAM Identity Center groups, Amazon Q will redirect you to the IAM Identity Center console to configure groups before you can add them to your applicaton.

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

      • Connect to organization instance of IAM Identity Center – Select this option to manage access to Amazon Q by assigning users and groups from the Identity Center directory for your organization.

      • Connect to account instance of IAM Identity Center – Select this option to manage access to Amazon Q by assigning existing users and groups from your Identity Center directory.

      • The region your Amazon Q application is in. This is so you can make sure that the region for your Amazon Q aplication and IAM Identity Center instance match.

      • IAM Identity Center – The ARN for your IAM Identity Center instance.

    3. If you have an IAM Identity Center account instance configured, your account instance will be auto-detected and you will see the following:

      • The region your Amazon Q application is in. This is so you can make sure that the region for your Amazon Q aplication and IAM Identity Center instance match.

      • IAM Identity Center – The ARN for your IAM Identity Center instance.

    4. If you have an IAM Identity Center organization instance configured, you will see a message asking you to tell your admin to give you access to IAM Identity Center. You will need access to IAM Identity Center before you can proceed.

  7. Tags – optional – To add tags to your Amazon Q application 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, see Tags.

  8. To start creating your application, choose Create.

AWS CLI

To configure an Amazon Q application

aws qbusiness create-application \ --display-name application-name \ --role-arn roleArn \ --description optional-app-description \ --enryption-configuration kmsKeyId=<kms-key-id> \ --attachments-configuration attachmentsControlMode=ENABLED

Creating an Amazon Q application (external IdP)

The following tabs provide a procedure for creating an application that uses an external identity provider to manage user access. by using the AWS Management Console and code examples for using the AWS CLI.

Console

To configure an Amazon Q application

  1. Sign in to the AWS Management Console and open the Amazon Q console at https://console.aws.amazon.com/amazonq/.

  2. For Create Amazon Q application, choose Get started.

  3. For Applications, choose Create application. The console will display a Select access management method for application dialog box.

  4. In Select access management method for application, choose Legacy identity management and then select Ok. Choosing this option allows you to use SAML 2.0 to manage user identities using an identity provider of your choice.

  5. For Application settings, enter the following information for your Amazon Q application:

    • Application name – A name for your Amazon Q Business application 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.

    • Service access – An IAM role for Amazon Q Business to allow it to access the AWS resources it needs to create your application. You can choose to use an existing role or create a new role.

      Note

      For more information about example service roles, see IAM role for an Amazon Q Business application.

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

    • Encryption – Amazon Q 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. To learn more, see Data encryption.

      Important

      If you choose to use a customer managed key, you must provision at least 10 index storage units when you create an Amazon Q retriever.

  6. Tags – optional – To add tags to your Amazon Q application 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, see Tags.

  7. To start creating your application, choose Create.

AWS CLI

To configure an Amazon Q application

aws qbusiness create-application \ --display-name application-name \ --role-arn roleArn \ --description optional-app-description \ --enryption-configuration kmsKeyId=<kms-key-id> \ --attachments-configuration attachmentsControlMode=ENABLED