# Creating an Amazon Q Business application using Identity Federation through IAM
<a name="create-application-iam"></a>

This section walks you through creating and configuring an Amazon Q Business application using IAM federation to manage end user access.

Amazon Q Business supports identity federation through AWS Identity and Access Management. When you use identity federation, you can manage users with your enterprise identity provider (IdP) and use AWS Identity and Access Management to authenticate users when they sign in to Amazon Q Business.

You can use any third-party identity provider that supports Security Assertion Markup Language 2.0 (SAML 2.0) or OpenID Connect (OIDC) to provide an onboarding flow for your Amazon Q Business users. Such identity providers include, but aren't limited to Okta and Ping Identity.

**Important**  
Amazon Q Business supports Microsoft Entra ID with SAML 2.0, but doesn't support OIDC for Google or Microsoft Entra ID.

With identity federation, your users get one-click access to their Amazon Q Business applications using their existing identity credentials. You also have the security benefit of identity authentication by your identity provider. You can control which users have access to Amazon Q Business using your existing identity provider.

**Note**  
Federated groups aren't supported through IAM Federation. If you want to ingest federated groups, use the [PutGroup](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_PutGroup.html) API.

**Topics**
+ [Creating an Amazon Q Business application using IAM Federation through Okta](create-application-iam-okta.md)
+ [Creating an Amazon Q Business application using IAM federation through Microsoft Entra ID](create-application-iam-entraid.md)
+ [Connecting multiple Amazon Q Business applications to an Identity Provider](multiple-qbusiness-apps-idp.md)
+ [Making authenticated Amazon Q Business API calls using IAM federation](making-sigv4-authenticated-api-calls-iam.md)
+ [Managing Amazon Q Business resources](managing-resources-iam.md)

# Creating an Amazon Q Business application using IAM Federation through Okta
<a name="create-application-iam-okta"></a>

As the first step toward creating a generative artificial intelligence (AI) assistant, configure your external identity provider and connect it to AWS Identity and Access Management.

When you create an application environment, you can also choose to create an Amazon Q Business web experience, which your end users can use to chat with your application. You can also add subscriptions for end users who log in to your Amazon Q Business web experience using Okta. Any user logging in to your web experience is automatically provisioned with a subscription of a type that you select for them.

**Note**  
As of Oct 31, 2024, once you have created a new Amazon Q Business application environment, the default web experience will allow users to interact directly with the LLM to get answers from its general knowledge or uploaded file content, even if the Admin has not yet connected any enterprise data sources.  
For existing application environments, the *Allow direct access to LLM* setting will remain as previously configured. For new application environments, the *Allow direct access to LLM* setting will be enabled by default, though Admins can still disable this if desired.

To learn more about identity federation using AWS Identity and Access Management, see the following topics:
+ [Identity federation in AWS](https://aws.amazon.com/identity/federation/) on the *AWS website*.
+ [Providing access to externally authenticated users (identity federation)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_federated-users.html) in the *IAM User Guide*.

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.

**Topics**
+ [Prerequisites](#create-iam-app-okta-prereqs)
+ [Step 1: Create and configure an Okta application](#create-iam-app-okta-1)
+ [Step 2: Add an identity provider in IAM](#create-iam-app-okta-2)
+ [Step 3: Connect IAM to Okta](#create-iam-app-okta-3)
+ [Step 4: Create Amazon Q Business application](#create-iam-app-okta-saml-4)

## Prerequisites
<a name="create-iam-app-okta-prereqs"></a>

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](https://help.okta.com/en-us/Content/Topics/users-groups-profiles/usgp-people.htm) 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](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/web-experience-iam-role-iam.html) 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](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) in the AWS Identity and Access Management User Guide.
+ (Optional) Checked [how subscriptions work](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tiers.html#managing-sub-tiers-iam) for Amazon Q Business applications using IAM Federation.

## Step 1: Create and configure an Okta application
<a name="create-iam-app-okta-1"></a>

This procedure outlines how to create and configure an Okta instance for an Amazon Q Business application using a built-in web experience and a custom Amazon Q Business application client you develop using Amazon Q Business APIs.

**Important**  
Amazon Q Business supports Microsoft Entra ID with SAML 2.0, but doesn't support OIDC for Google or Microsoft Entra ID.

------
#### [ SAML ]

**To create an Okta instance **

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

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

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

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

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

   1. Deselect the **Use this for Recipient URL and Destination URL** box.

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

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

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

   1. For **Name ID format**, set to **Persistent**.

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

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

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

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

   1. Then, choose **Done**.

1. 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 4 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](https://help.okta.com/oie/en-us/Content/Topics/Apps/Apps_App_Integration_Wizard_SAML.htm) on the *Okta Help Center* website.

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

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

1. On the **Create a new app integration** page, do the following:
   + Choose **OIDC – OpenID Connect**.
   + Choose **Web application**.
   + Then, choose **Next**.

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

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

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

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

1. 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 Okta, the **Value** will be the following: `{"principal_tags": {"Email": {user.email} }}`. For other identity providers, use a valid JSON object in the following format:

     ```
     "principal_tags": {
         "Email": [email]
     }
     ```
**Note**  
To activate [Amazon Q Business response personalization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/personalizing-chat-responses.html) 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.

**Important**  
Amazon Q Business supports Microsoft Entra ID with SAML 2.0, but doesn't support OIDC for Google or Microsoft Entra ID.

------

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
<a name="create-iam-app-okta-2"></a>

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.

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

1. From **Identity providers**, select **Add provider**.

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

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

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

1. 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** drop-down, 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**.

1. 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](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/web-experience-iam-role-iam.html).
**Note**  
To create a new policy, follow the instructions in [Creating IAM policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) in the AWS Identity and Access Management User Guide.

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

1. 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\$1id* with your AWS account ID and *saml\$1provider* with the *assigned-iam-idp-name* you copied from your IAM identity provider ARN you copied:  
****  

     ```
     {
         "Version":"2012-10-17",		 	 	 
         "Statement": [
             {
                 "Action": "sts:AssumeRoleWithSAML",
                 "Sid": "SAMLAssumeRoleAccess",
                 "Effect": "Allow",
                 "Condition": {
                     "StringEquals": {
                         "SAML:aud": "https://signin.aws.amazon.com/saml"
                     }
                 },
                 "Principal": {
                     "Federated": "arn:aws:iam::111122223333:saml-provider/saml-provider-name"
                 }
             },
             {
                 "Action": "sts:TagSession",
                 "Sid": "SAMLTagSessionAccess",
                 "Effect": "Allow",
                 "Condition": {
                     "StringLike": {
                         "aws:RequestTag/Email": "*"
                     }
                 },
                 "Principal": {
                     "Federated": "arn:aws:iam::111122223333:saml-provider/saml-provider-name"
                 }
             }
         ]
     }
     ```
   + Then, select **Update policy**.

You are now ready to return to Okta to complete the process of establishing 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.

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

1. From **Identity providers**, select **Add provider**.

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

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

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

1. Then, on the **Selected trusted entity** page, do the following:
   + For **Trusted entity type** select **Web identity**.
   + In **Web identity**, from the **Identity provider** drop-down, select the identity provider you added.
   + For **Audience**, select your Client ID.
   + Select **Next**.

1. 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](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/web-experience-iam-role-iam.html).
**Note**  
To create a new policy, follow the instructions in [Creating IAM policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) in the AWS Identity and Access Management User Guide.

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

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

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

   ```
   
   
   ```

1. Then, select **Update policy**.

Now, move on to the Amazon Q Business console to create your application.

------

## Step 3: Connect IAM to Okta
<a name="create-iam-app-okta-3"></a>

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.

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

1. In **General**, from **SAML Settings** choose **Edit**.

1. In **Edit SAML**, for **General Settings** choose **Next**.

1. 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 drop-down list.
**Note**  
You can add more attributes to enable [Amazon Q Business response personalization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/personalizing-chat-responses.html). 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 drop-down 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 drop-down 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
<a name="create-iam-app-okta-saml-4"></a>

To create an Amazon Q Business application environment, you can use either the AWS Management Console or the Amazon Q Business API. When you create an application, response generation from large language model (LLM) knowledge is enabled by default.

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.

You also add subscriptions for end users logging into your Amazon Q Business web experience using Okta. Any user logging into your web experience is automatically provisioned a subscription of the type you select.

**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](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html) for user management to avoid this issue. 

For a consolidated view of your user subscriptions—including a list of subscribed users, their subscription status, and applications, accounts, or services a user can access through their subscriptions—see the [Amazon Q subscriptions page](https://console.aws.amazon.com/amazonq/subscriptions). 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](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tiers.html#managing-sub-tiers-iam).

As a prerequisite, make sure that you complete the [setting up](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html) tasks. If you're using the AWS CLI or the API, make sure that you created the required [IAM roles](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html).

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.

1. On the **Create application** page, for **What kind of application do you want to create?**, enter the following information for your Amazon Q Business application:

   1. **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. Amazon Q Business auto-generates an application name for you, unless you choose to enter a custom name.

   1. **Outcome** – Select **Web experience** to create a web experience for your application. Amazon Q Business creates a web experience by default when you create an application. If you don't want to create a web experience, deselect this option.

1. For **Access management method**, choose **AWS IAM Identity Provider**.

   Then, for **Choose an identity provider type**, choose between **Security Assertion Markup Language (SAML)** and **OpenID Connect (OIDC)**.

   1. For **SAML**, do the following:

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

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

   1. For **OIDC**, do the following:

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

      1. For **ClientID for OIDC**, input the OIDC client ID you copied in Step 1.

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

      1. In **Choose method to authorize Amazon Q Business web experience to use Secrets**, 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](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/web-experience-iam-role-iam.html).
**Note**  
To create a new policy, follow the instructions in [Creating IAM policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) in the AWS Identity and Access Management User Guide.

1. For **Default subscription settings**, for **Subscription 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.

1. For **Application details** – Amazon Q Business chooses the following configuration settings for your application by default:

   1. For **Application service access** – Amazon Q Business will create a new service-linked role for your application.

   1. **Encryption** – Amazon Q Business will create an AWS owned AWS KMS key to encrypt your data.

   1. For **Web experience service access** – If you've chosen to create a web experience, Amazon Q Business requires you select an existing role to allow end users to log in to a Amazon Q Business web experience.

1. (Optional) To customize **Application details**, expand the **Application details section**, and then do the following:

   1. In **Application service access**, for **Choose a method to authorize Amazon Q Business**, choose from the following options:

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

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

      1. **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](create-application-iam-role.md). For information on service-linked roles, including to manage them, see [Using service-linked roles](https://docs.aws.amazon.com/amazonq/latest/business-use-dg/using-service-linked-roles.html). 

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

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

   1. In **Web experience service access**, enter the following information:

      1. For **Choose a method to authorize Amazon Q Business** – A service access role assumed by end users when they sign in to your web experience that grants them permission to start and manage conversations Amazon Q Business. You can only choose to use an existing role. For more information on how to create a role and permissions needed, see [Prerequisites for creating an IAM federated application](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam-okta.html#create-iam-app-okta-prereqs).

      1. **Service role name** – A name for the service role you created for easy identification on the console.

1. To start creating your application, choose **Create**.
**Note**  
If you're creating a web experience, you can also choose to create your application and [view your web experience](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/customizing-web-experience-iam.html) by selecting **Create and open web experience**.

1. 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 and then, depending on the authentication type you've chosen, do the following:

   1. **If you're using SAML** – Add `/saml` at the end of the URL. Then, 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.

   1. **If you're using OIDC** – Add `/authorization-code/callback` at the end of the URL. 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.

------
#### [ 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 \
--encryption-configuration kmsKeyId=<kms-key-id> \
--attachments-configuration attachmentsControlMode=ENABLED
```

------

You've finished configuring your Amazon Q Business application. Your authenticated end users can now log in and chat with your web experience. 

# Creating an Amazon Q Business application using IAM federation through Microsoft Entra ID
<a name="create-application-iam-entraid"></a>

As the first step toward creating a generative artificial intelligence (AI) assistant, configure your external identity provider and connect it to AWS Identity and Access Management.

When you create an application environment, you can also choose to create an Amazon Q Business web experience, which your end users can use to chat with your application. You can add subscriptions for end users who log in to your Amazon Q Business web experience using Microsoft Entra ID. Any user logging in to your web experience is automatically provisioned with a subscription of a type that you select for them.

**Note**  
As of Oct 31, 2024, once you have created a new Amazon Q Business application environment, the default web experience will allow users to interact directly with the LLM to get answers from its general knowledge or uploaded file content, even if the Admin has not yet connected any enterprise data sources.  
For existing application environments, the *Allow direct access to LLM* setting will remain as previously configured. For new application environments, the *Allow direct access to LLM* setting will be enabled by default, though Admins can still disable this if desired.

To learn more about identity federation using AWS Identity and Access Management, see the following topics:
+ [Identity federation in AWS](https://aws.amazon.com/identity/federation/) on the *AWS website*.
+ [Providing access to externally authenticated users (identity federation)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_federated-users.html) in the *IAM User Guide*.

The following steps show how to integrate Amazon Q Business with Microsoft Entra ID. Integrating Amazon Q Business with Microsoft Entra ID requires that you switch between tasks on the Amazon Q Business console and the Microsoft Entra ID admin portal.

**Topics**
+ [Prerequisites](#create-iam-app-entraid-prereqs)
+ [Step 1: Create and configure a Microsoft Entra ID application](#create-iam-app-entraid-1)
+ [Step 2: Create an IAM identity provider](#create-iam-app-entraid-2)
+ [Step 3: Update your Microsoft Entra ID application with the IAM role ARN](#create-iam-app-entraid-3)
+ [Step 4: Create an Amazon Q Business application](#create-iam-app-entraid-4)
+ [Step 5: Update your Microsoft Entra ID application with the web experience URL](#create-iam-app-entraid-5)
+ [Troubleshooting Microsoft Entra ID integration](#create-iam-app-entraid-troubleshooting)

## Prerequisites
<a name="create-iam-app-entraid-prereqs"></a>

Before you start to integrate Amazon Q Business with Microsoft Entra ID, make sure that you have:
+ Created a Microsoft Entra ID account and added at least one user with a valid email address. For more information, see [Add users in Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/fundamentals/add-users) on the *Microsoft Learn website*.
+ Appropriate permissions in Microsoft Entra ID to create and configure enterprise applications. Review the [Microsoft Entra ID built-in roles documentation](https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/permissions-reference) to ensure you have the required permissions. Typically, you need the `Application Administrator` or `Cloud Application Administrator` role.
+ Created IAM policies containing the permissions outlined in [IAM role for an Amazon Q Business web experience using IAM Federation](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/web-experience-iam-role-iam.html) 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

  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](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) in the AWS Identity and Access Management User Guide.
+ (Optional) Checked [how subscriptions work](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tiers.html#managing-sub-tiers-iam) for Amazon Q Business applications using IAM Federation.

## Step 1: Create and configure a Microsoft Entra ID application
<a name="create-iam-app-entraid-1"></a>

This procedure outlines how to create and configure a Microsoft Entra ID instance for an Amazon Q Business application using a built-in web experience and a custom Amazon Q Business application client you develop using Amazon Q Business APIs.

**Important**  
Amazon Q Business supports Microsoft Entra ID with SAML 2.0 only. OIDC is not supported for Microsoft Entra ID.

**To create a Microsoft Entra ID instance**

1. Sign into the Microsoft Entra admin center in your Microsoft Azure Portal.

1. In the left navigation pane, choose **Enterprise apps**.

1. From **All applications**, choose **\$1 New application** from the top navigation pane.

1. On the **Browse Microsoft Entra gallery** page, choose **Amazon Web Services (AWS)**, and then select **AWS Single-Account Access**.

1. Then, in the **AWS Single-Account Access** menu that opens, in **Name**, add a name for your application. For example: *QBusinessSAMLProvider*. Then, select **Create**.

1. When the application is ready, on the **Overview** page of your application, from **Getting Started** choose **Single sign-on**.

1. On the **Single sign-on** page, for **Select a single sign-on method**, select **SAML**.

   Selecting SAML configures the application to use Security Assertion Markup Language (SAML) 2.0 for authentication, which is the protocol required for IAM federation with AWS services like Amazon Q Business.

1. On the **Set up Single Sign-On with SAML** page, for **Basic SAML Configuration**, choose **Edit**, and then configure the following settings:
   + For **Identifier (Entity ID)**, enter your web application endpoint.

     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*. The 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: *https://sampleurl.com*. You will update this at the end of your Amazon Q Business application creation process.
   + For **Reply URL (Assertion Consumer Service URL)** – Enter your web application endpoint.

     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*. The 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: *https://sampleurl.com*. You will update this at the end of your Amazon Q Business application creation process.
   + Select **Save**.

1. In the **SAML Certificates** section, download the **Federation Metadata XML** file. You will need this file when you create an identity provider in IAM.

   The **Federation Metadata XML** file contains all the necessary SAML metadata that IAM needs to establish trust with your Microsoft Entra ID application, including certificate information, entity IDs, and endpoint URLs. This file will be uploaded to IAM when creating the identity provider in the next step.

You're now ready to move on to configuring AWS Identity and Access Management on the AWS Management Console.

## Step 2: Create an IAM identity provider
<a name="create-iam-app-entraid-2"></a>

After you create and configure your Microsoft Entra ID application, create an IAM identity provider.

**To connect Microsoft Entra ID to AWS Identity and Access Management **

1. Sign in to the AWS Management Console and open the AWS Identity and Access Management.

1. In the navigation pane, choose **Identity providers**, and then choose **Add provider**.

1. For **Configure provider**, do the following:

   1. For **Provider type**, choose **SAML**.

   1. For **Provider name**, enter a name for your identity provider (for example, *EntraIDProvider*).

   1. For **Metadata document**, choose **Choose file** and upload the **Federation Metadata XML** file that you downloaded from Microsoft Entra ID.

   1. Choose **Add provider**.

1. 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 IAM trust policy and when you connect your AWS Identity and Access Management identity provider to your Microsoft Entra ID 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.

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

1. Then, on the **Selected trusted entity** page, do the following:
   + For **Trusted entity type** select **Custom trust policy**.
   + In **Custom trust policy**, add the following trust policy, replacing the value for *AWS IAM Identity Provider ARN* with the identity provider ARN you copied in the previous step:  
****  

     ```
     
     
     ```
**Note**  
Leave the `SAML:aud` field as *https://sampleurl.com* for now. You'll come back to update it with your Amazon Q web experience URL as part of Step 5 of this tutorial.

     Select **Next**.

1. 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](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/web-experience-iam-role-iam.html). Optionally, select **AdministratorAccess**.
**Note**  
To create a new policy, follow the instructions in [Creating IAM policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) in the AWS Identity and Access Management User Guide.

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

1. 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 Microsoft Entra ID. The format of the ARN will be like this: `arn:aws:iam::111122223333:role/sample-role`.

You are now ready to return to Microsoft Entra ID to complete the process of establishing a trust relationship between AWS Identity and Access Management and Microsoft Entra ID.

## Step 3: Update your Microsoft Entra ID application with the IAM role ARN
<a name="create-iam-app-entraid-3"></a>

In this step, you complete configuring the trust relationship between AWS Identity and Access Management and Microsoft Entra ID.

**To update your Microsoft Entra ID application**

1. Return to the Microsoft Azure Portal and navigate to the application you created.

1. In the left navigation pane, choose **Single sign-on**, then choose **Manage**. Then, choose **Single sign-on**.

1. In **Single sign-on** section, choose **Attributes & Claims**, and select **Edit**.

1. From **Required claim**, select **Unique User Identifier (Name ID)**.

1. In **Manage claim**, do the following:
   + For **Name identifier format**, choose **Persistent**.
   + For **Source attribute**, choose **user.objectid**.
   + Select **Save**.

1. Then, from **Attributes & Claims** select **Add new claim**, and in **Manage claim**, do the following:
   + For **Name** – Type **PrincipalTag:Email**.
   + For **Namespace**, type **https://aws.amazon.com/SAML/Attributes**.
   + Leave **Source** value as **Attribute**.
   + For **Source attribute**, choose **user.mail**.
   + Select **Save**.

1. Then, from your application menu, choose **Manage** and then select **Security**.

1. From **Security**, select **Permissions**.

1. In **Permissions**, choose **Application registration**.

1. From **Application registration** from the left navigation menu, select **App roles**, and then select **Create app role**. In the **Create app role** dialog box that opens, and do the following:
   + For **Display name**, add a name for your role.
   + For **Allowed member types**, choose **Both (Users/Groups \$1 Applications)**.
   + 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/entra-idp`.
   + For **Description**, add a description for your app role.
   + Select **Apply**.

1. Then, in the left navigation pane of your application, choose **Users and groups**, and do the following steps.

   1. Choose **\$1 Add user/group** and select the users or groups you want to assign to your application, and then choose **Select**.

   1. Choose **Assign**.

1. Refresh your page. Then, from the left navigation pane of your application, choose **Manage**. Then, select **API Permissions**, and **Add a permission**.

1. In **Add a permission**. Then, on the **Request API permissions** section, do the following:

   1. Choose **APIs my organization uses** and select and open the Entra ID application you created.

   1. For **What type pf permissions does your application require?** – Choose **Application permissions**.

   1. In **Permissions** – Choose the app role permissions you created in the last step.

   1. Select **Add permissions**.

1. Then, from **Manage**, select **Properties** and copy and save the **User access URL** value for your application.

   You will need this value to create your Amazon Q application.

Your Entra ID setup is complete. You're now ready to begin creating your Amazon Q Business application.

## Step 4: Create an Amazon Q Business application
<a name="create-iam-app-entraid-4"></a>

After you configure Microsoft Entra ID and IAM, create an Amazon Q Business application.

**To create an Amazon Q Business application**

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

1. In the navigation pane, choose **Applications**, and then choose **Create application**.

1. On the **Create application** page, for **What kind of application do you want to create?**, enter the following information for your Amazon Q Business application:

   1. **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. Amazon Q Business auto-generates an application name for you, unless you choose to enter a custom name.

   1. For **User access**, choose **Authenticated access**.

   1. For **Outcome**, choose **Web experience**.

1. For **Access management method**, choose **AWS IAM Identity Provider**.

   Then, for **Choose an identity provider type**, choose **Security Assertion Markup Language (SAML)**.

   For **SAML**, do the following:

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

   1. For **Authentication URL**, provide the authentication URL for Entra ID. Your authentication URL must be of the following format: `https://myapps.microsoft.com/signin/app_name/user_access_url_suffix`.

      For the `user_access_url_suffix`, copy the value of everything after `https://myapps.microsoft.com/signin/` from the **User access URL** you copied and saved in the last step.

      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.

1. For **Default subscription settings**, for **Subscription 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.

1. For **Application details** – Amazon Q Business chooses the following configuration settings for your application by default:

   1. For **Application service access** – Amazon Q Business will create a new service-linked role for your application.

   1. **Encryption** – Amazon Q Business will create an AWS owned AWS KMS key to encrypt your data.

   1. For **Web experience service access** – If you've chosen to create a web experience, Amazon Q Business requires you select an existing role to allow end users to log in to a Amazon Q Business web experience.

1. (Optional) To customize **Application details**, expand the **Application details section**, and then do the following:

   1. In **Application service access**, for **Choose a method to authorize Amazon Q Business**, choose from the following options:

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

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

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

      1. **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](create-application-iam-role.md). For information on service-linked roles, including to manage them, see [Using service-linked roles](https://docs.aws.amazon.com/amazonq/latest/business-use-dg/using-service-linked-roles.html). 

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

   1. In **Web experience service access**, enter the following information:

      1. For **Choose a method to authorize Amazon Q Business** – A service access role assumed by end users when they sign in to your web experience that grants them permission to start and manage conversations Amazon Q Business. Choose the IAM role you created in Step 2.

1. To start creating your application, choose **Create**.
**Note**  
If you're creating a web experience, you can also choose to create your application and [view your web experience](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/customizing-web-experience-iam.html) by selecting **Create and open web experience**.

1. 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 and add `/saml` at the end of the web experience URL.

1. Then, open IAM on the AWS Management Console, and do the following:

   1. From the left navigation menu, for **Access management**, choose **Roles**, and then choose the IAM role you created in Step 2 of this tutorial. 

   1. From the role summary page, select **Trust relationships**, and then select **Edit trust policy**. 

   1. Replace the placeholder `{{https://sampleurl.com}}` with the Amazon Q web application URL you copied in the previous step.

   1. Select **Update policy**.

You've finished configuring your Amazon Q Business application. You're now ready to return to Entra ID to make the final changes needed to successfully launch your web experience application. 

## Step 5: Update your Microsoft Entra ID application with the web experience URL
<a name="create-iam-app-entraid-5"></a>

After you create your Amazon Q Business application and web experience, update your Microsoft Entra ID application with the web experience URL.

 Return to the Entra ID console, edit the Basic SAML Configuration of your Entra ID application to update the **Identifier (Entity ID)** and **Reply URL (Assertion Consumer Service URL)** you added in Step 1 to your web experience URL. Remember to save your changes.

**To update your Microsoft Entra ID application**

1. Return to the Microsoft Entra admin center and navigate to your application.

1. In the left navigation pane, choose **Single sign-on**.

1. In the **Basic SAML Configuration** section, choose **Edit**.

1. Update the following fields with your Amazon Q Business web experience URL:

   1. For **Identifier (Entity ID)**,replace *https://sampleurl.com* with your web experience URL with the `/saml` suffix added. For example: *https://abcdefgh.qbusiness.us-east-1.on.aws/saml*.

   1. For **Reply URL (Assertion Consumer Service URL)**, replace *https://sampleurl.com* with your web experience URL with `/saml` added at the end. For example: *https://abcdefgh.qbusiness.us-east-1.on.aws/saml*.

1. Choose **Save**.

You've finished configuring your Amazon Q Business for chat. Your authenticated end users can now log in and chat with your web experience.

## Troubleshooting Microsoft Entra ID integration
<a name="create-iam-app-entraid-troubleshooting"></a>

If you encounter issues with your Microsoft Entra ID integration, check the following:

**SAML assertion validation errors**  
If you receive errors about invalid SAML assertions, verify that:  
+ The **Identifier (Entity ID)** is set to `https://signin.aws.amazon.com/saml`.
+ The **Reply URL** ends with `/saml` and matches your web experience URL exactly.
+ All three required SAML attributes are correctly configured: `Role`, `RoleSessionName`, and `PrincipalTag:Email`.

**Access denied errors**  
If users receive access denied errors when trying to access the Amazon Q Business web experience, check that:  
+ The IAM role ARN and identity provider ARN in the `Role` attribute are correct and separated by a comma.
+ The IAM role has the necessary permissions for Amazon Q Business web experience access.
+ The trust relationship in the IAM role is correctly configured to trust the SAML identity provider.

**User not provisioned errors**  
If users receive errors about not being provisioned in Amazon Q Business, verify that:  
+ The `PrincipalTag:Email` attribute is correctly configured to use `user.mail`.
+ The user has a valid email address in Microsoft Entra ID.
+ The default subscription tier is correctly set in the Amazon Q Business application.

**Testing SAML configuration**  
To test your SAML configuration:  

1. In the Microsoft Entra admin center, navigate to your application.

1. Choose **Single sign-on**, then scroll down to **Test single sign-on with <application name>**.

1. Choose **Test** to sign in as the current user, or choose **Test as another user** to sign in as a different user.

1. If the test is successful, you'll be redirected to your Amazon Q Business web experience.

For SAML assertion validation errors, access denied errors, and user not provisioned errors, you'll need to check the Microsoft Entra ID configuration in the admin portal as described in the Console tab.

For more information about SAML federation with Microsoft Entra ID, see [Set up SAML-based single sign-on](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal-setup-sso) in the Microsoft Entra documentation.

# Connecting multiple Amazon Q Business applications to an Identity Provider
<a name="multiple-qbusiness-apps-idp"></a>

You can connect multiple Amazon Q Business custom applications to a single SAML 2.0 or OIDC based identity provider (IdP) application. Connecting multiple Amazon Q Business applications to a single identity provider enables end users access Amazon Q Business with all their web-based tools and services through a single sign-on (SSO) provided by the IdP.

Most IdPs allow you to configure additional custom web applications alongside existing ones. In this section we use Okta as an example to show you the specific steps to configure a new custom application.

**Important**  
Amazon Q Business supports Microsoft Entra ID with SAML 2.0, but doesn't support OIDC for Google or Microsoft Entra ID.

**Topics**
+ [Using SAML](#multiple-qbusiness-apps-idp-saml)
+ [Using OIDC](#multiple-qbusiness-apps-idp-oidc)

## Using SAML
<a name="multiple-qbusiness-apps-idp-saml"></a>

In this section we use Okta as an example to show you the specific steps to configure a new custom application using SAML 2.0.

**To connect multiple Amazon Q Business custom applications to Okta**

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

1. In the left navigation pane, choose **Applications**, and then choose your existing SAML 2.0 application.

1. From **General**, choose **SAML settings**.

1. Keep your **General Settings** as is and select **Next**.

1. In **Edit SAML Integration**, for **SAML Settings**, under **General**, make sure you've already entered the **Single sign-on URL** and **Audience URI** for your first SAML application. For steps on how to do this, see [Create and configure an Okta application](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html#create-iam-app-okta-1).

1. Then, from **General**, select **Show Advanced Settings**.

1. Scroll down to **Other Requestable SSO URLs** and select **Add Another**.

1. Then, add a **Single sign-on URL** for each additional SAML application you want to configure, and provide an index value for each. Example URL format: *http://localhost:8000/saml*.

1. Then, scroll down and select **Next**.

1. On the **Feedback** page, select **Finish**.

You're done with setting up your Okta application for multiple Amazon Q Business applications.

To make a request to this URI, you need to construct a SAML request in the following format:

```
<samlp:AuthnRequest 
    xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" 
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" 
    ID="_uniqueID12345" 
    Version="2.0" 
    IssueInstant="2024-08-08T12:00:00Z" 
    ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" 
    Destination="https://idp-sso-url/sso"  
    AssertionConsumerServiceIndex="0"
    <saml:Issuer>https://sp.example.com/</saml:Issuer>
    <samlp:NameIDPolicy Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" AllowCreate="true"
</samlp:AuthnRequest>
```

Then, you send a SAML request to your to your custom web application's URI with index 0. The SAML request is usually sent via HTTP redirect, which requires the XML to be Base64 encoded. This can be done programmatically in various languages. For example, in JavaScript, you would do the following:

```
const samlRequest = '<samlp:AuthnRequest ...>...</samlp:AuthnRequest>'; // Your SAML request
const encodedRequest = btoa(samlRequest); // Base64 encoding
```

After encoding, redirect the user to the IdP with the following SAML request as parameter:

```
window.location.href = `https://idp.example.com/sso?SAMLRequest=$${encodedRequest}`;
```

## Using OIDC
<a name="multiple-qbusiness-apps-idp-oidc"></a>

You can configure multiple redirect URLs for a single OpenID Connect (OIDC) application. In this section we use Okta as an example to show you the specific steps to configure a new custom application using OIDC.

**To connect multiple Amazon Q Business custom applications to Okta**

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

1. From **General**, scroll down to **General Settings**, and then select **Edit**.

1. From **LOGIN**, for **Sign-in redirect URIs**, and then select **Edit**.

1. In **Sign-in redirect URIs**, choose **Add URI** to add multiple URIs. Then, select **Save**.

You're done with setting up your Okta application for multiple Amazon Q Business applications.

# Making authenticated Amazon Q Business API calls using IAM federation
<a name="making-sigv4-authenticated-api-calls-iam"></a>

Amazon Q Business can securely handle data with integrated authentication and authorization. During data ingestion, Amazon Q Business preserves the authorization information—access control lists (ACLs)—from the data source so users can only request answers from the data they already have access to. Through IAM Federation, Amazon Q Business uses [trusted identity propagation](https://docs.aws.amazon.com/singlesignon/latest/userguide/using-apps-with-trusted-token-issuer.html) to ensure that an end user is authenticated and receives fine-grained authorization to their user ID and group-based resources.

In order to achieve this, a subset of the Amazon Q Business APIs ([Chat](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_Chat.html), [ChatSync](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ChatSync.html), [SearchRelevantContent](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_SearchRelevantContent.html), [ListConversations](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListConversations.html), [ListMessages](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListMessages.html), [DeleteConversation](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DeleteConversation.html), [PutFeedback](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_PutFeedback.html)) require identity-aware [AWS Sig V4 credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/signing-elements.html) for the authenticated user on whose behalf the API call is being made.

This page provides an overview of the workflows needed to obtain AWS Sig V4 credentials for a user authenticated using an identity provider (IdP), such as Okta. While we use Okta as an example, the same principles and steps apply to any other identity provider synced with your IAM instance.

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

**Note**  
Federated groups aren't supported through IAM Federation. If you want to ingest federated groups, use the [PutGroup](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_PutGroup.html) API.

**Topics**
+ [Prerequisites](#sigv4-auth-api-calls-prereqs-iam)
+ [One-time setup](#control-plane-setup-iam)
+ [Workflow for each API call session for authenticated user](#data-plane-workflow-iam)

## Prerequisites
<a name="sigv4-auth-api-calls-prereqs-iam"></a>

Before you begin setting up for making Sig V4 authenticated API calls, make sure you've done the following:
+ [Created an Amazon Q Business application](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateApplication.html).
+ Created an Okta IdP instance and configured users and groups within it. While we use Okta as an example, the same principles and steps apply to any other identity provider connected to your IAM instance.
+ Created an IAM instance for your Amazon Q Business application and connected Okta as your identity source.
+ Configured access to the AWS CLI.

## One-time setup
<a name="control-plane-setup-iam"></a>

The following section outlines the steps to set up the Amazon Q Business control plane. You only need to perform these steps once.

1. Create an [OIDC app integration](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_oidc.htm) in Okta.

1. Create the IAM identity provider using the following command:

   ```
   aws iam \
   create-open-id-connect-provider \
   --url issuer-url
   ```

   Then, copy the `OpenIDConnectProviderArn` from the output.

1. Next, create the IAM role. To do so, perform the following steps:

   1. Create a directory named `policies`.

   1. In that directory, create and save a file named `trustpolicyforfederation.json` with the following JSON included:

1. Next, create the IAM policy for your web experience. To do so, perform the following steps:

   1. In the `policies` directory, create and save a new file named `permspolicyforfederation.json` with the following JSON included:

1. Finally, create and attach the roles in IAM using the following command:

   ```
   aws iam \
   create-role \
   --role-name 
   --assume-role-policy-document file://policies/trustpolicyforfederation.json \
   --policy-document file://policies/permspolicyforfederation.json
   ```

## Workflow for each API call session for authenticated user
<a name="data-plane-workflow-iam"></a>

1. First, use the `IdToken` from Okta to call the [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html) API to get AWS credentials. To do so, use the following command:

   ```
   aws sts
   assume-role-with-web-identity
   --role-arn role arn
   --role-session-name session-name
   --web-identity-token id-token-from-okta
   ```

1. Then, set the following environment variables in your command line environment using the credentials you received as a response from the [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html) API call.

   ```
   AWS_ACCESS_KEY_ID="identity-aware-sigv4-access-key"
   AWS_SECRET_ACCESS_KEY="identity-aware-sigv4-secret-key"
   AWS_SESSION_TOKEN="identity-aware-sigv4-session-token"
   ```

1. Then, make Amazon Q Business API calls using the following command:

   ```
   aws qbusiness \
   chat-sync \
   --application-id application-id
   --user-message sample-chat-request
   ```

# Managing Amazon Q Business resources
<a name="managing-resources-iam"></a>

You can choose to manage your Amazon Q Business application environment and associated resources. To learn how to do so, see the following sections:
+ [Managing Amazon Q Business applications](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-app-actions-iam.html)
+ [Managing Amazon Q Business web experiences](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-exp-actions-iam.html)
+ [Managing user subscriptions](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/manage-user-subscriptions-iam.html)

# Managing Amazon Q Business applications
<a name="supported-app-actions-iam"></a>

To manage an Amazon Q Business application environment, you can take the following actions:

**Topics**
+ [Deleting an application](#delete-app-iam)
+ [Getting application environment properties](#describe-app-iam)
+ [Listing applications](#list-app-iam)
+ [Updating an application environment](#update-app-iam)

## Deleting an application
<a name="delete-app-iam"></a>

To delete an Amazon Q Business application environment, you can use the console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DeleteApplication.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DeleteApplication.html) API operation.

The following tabs provide a procedure for the console and code examples for the AWS CLI.

------
#### [ Console ]

**To delete an Amazon Q Business application** 

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

1. In **Applications**, choose **Actions**.

1. Choose **Delete**.

1. In the dialog box that opens, type **Delete** to confirm deletion, and then choose **Delete**.

   You are returned to the service console while your application environment is deleted. When the deletion process is complete, the console displays a message confirming successful deletion.

------
#### [ AWS CLI ]

**To delete an Amazon Q Business application environment**

```
aws qbusiness delete-application \
--application-id application-id
```

------

## Getting application environment properties
<a name="describe-app-iam"></a>

To get the properties of an Amazon Q Business application environment, you can use the console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_GetApplication.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_GetApplication.html) API operation.

The following tabs provide a procedure for the console and code examples for the AWS CLI.

------
#### [ Console ]

**To get properties of an Amazon Q Business application environment** 

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

1. For **Applications**, select the name of your application environment from the list of applications.

1. On **Application settings**, the following properties are available:
   + **Application name** – The name that you chose for your application environment. 
   + **Application ID** – The ID assigned to your application environment. 
   + **Subtitle** – The subtitle that you chose to assign to your application environment. 
   + **Service access** – The service access role that your application environment is using. 
   + **Title** – The title that you gave to your application environment. 
   + **Application status** – The status of your application environment.

   To update a setting, select **Edit**.

------
#### [ AWS CLI ]

**To get Amazon Q Business application properties **

```
aws qbusiness get-application \
--application-id application-id
```

------

## Listing applications
<a name="list-app-iam"></a>

To list Amazon Q Business applications, you can use the console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListApplications.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListApplications.html) API operation.

The following tabs provide a procedure for the console and code examples for the AWS CLI.

------
#### [ Console ]

**To list your Amazon Q Business application environments**

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

1. In **Applications**, all your configured application environments are listed.

------
#### [ AWS CLI ]

**To list Amazon Q Business application environments **

```
aws qbusiness list-applications \
--max-results max-results-to-return
```

------

## Updating an application environment
<a name="update-app-iam"></a>

To update an Amazon Q Business application environment, you can use the console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateApplication.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateApplication.html) API operation.

**Note**  
You can't update the retriever you've chosen or change users and groups added to the application environment when you update it. If you need to update your retriever, create a new application environment.  
If you're integrating your Amazon Q Business application environment with IAM Identity Center (IDC) as an [AWS-managed](https://docs.aws.amazon.com/singlesignon/latest/userguide/awsapps.html) application environment using and you want to update users and groups, you can do so from the [application environment summary](https://docs.aws.amazon.com/amazonq/latest/business-use-dg/supported-app-actions.html) page.

The following tabs provide a procedure for the console and code examples for the AWS CLI.

------
#### [ Console ]

**To update an Amazon Q Business application environment**

**Option 1**

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

1. In **Applications**, select the name of your application environment from the list of applications.

1. In **Applications**, choose **Actions**.

1. Choose **Edit**.

   On the **Update application** page, edit your application environment settings.

**Option 2**

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

1. In **Applications**, select the name of your application environment from the list of applications.

1. On the application page, select **Edit** from the page header, or select **Edit** from **Application settings**.

1. Choose **Edit**.

   On the **Update application** page, edit your application environment settings.

------
#### [ AWS CLI ]

**To update an Amazon Q Business application environment **

```
aws qbusiness update-application \
--application-id application-id \
--display-name application-name \
--role-arn roleArn \
--description application-description \
--attachments-configuration attachmentsControlMode=ENABLED
```

------

# Managing Amazon Q Business web experiences
<a name="supported-exp-actions-iam"></a>

To manage Amazon Q Business web experiences, you can take the following actions:

**Topics**
+ [Creating a web experience](#create-experience-iam)
+ [Deleting a web experience](#delete-web-experience-iam)
+ [Getting properties of a web experience](#describe-web-experience-iam)
+ [Listing web experiences](#list-web-experiences-iam)
+ [Updating a web experience](#update-web-experience-idp-iam)

## Creating a web experience
<a name="create-experience-iam"></a>

To create an Amazon Q Business web experience, you can use the console or the [CreateWebExperience](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateWebExperience.html) API operation.

The following tabs provide a procedure for the AWS Management Console and code examples for the AWS CLI.

------
#### [ Console ]

If you use the console, this action is spread across two steps: [Creating an Amazon Q Business application using Identity Federation through IAM](create-application-iam.md) and [Customizing web experience](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/customizing-web-experience-app.html). To create a web experience, you must create an application environment.

------
#### [ AWS CLI ]

**To create an Amazon Q Business web experience**

```
aws qbusiness create-web-experience \
--application-id application-id \ 
--sample-prompts-control-mode sample-prompts \      
--subtitle subtitle \     
--tags tags \ 
--title title \
--welcome-message welcome-message \
```

------

## Deleting a web experience
<a name="delete-web-experience-iam"></a>

To delete an Amazon Q Business web experience, you can use the console or the [DeleteWebExperience](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DeleteWebExperience.html) API operation.

If you're using the API, you can delete a web experience without deleting the application environment that it's a part of.

If you're using the console, the only way to delete your Amazon Q Business web experience is to delete the Amazon Q Business application environment that it's attached to.

The following tabs provide a procedure for the AWS Management Console and code examples for the AWS CLI.

------
#### [ Console ]

**To delete an Amazon Q Business web experience** 

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

1. In **Applications**, choose **Actions**.

1. Choose **Delete**.

1. In the dialog box that opens, type **Delete** to confirm deletion, and then choose **Delete**.

   You are returned to the service console while your application environment is deleted. When the deletion process is complete, the console displays a message confirming successful deletion. Both the application environment and the web experience are deleted.

------
#### [ AWS CLI ]

**To delete an Amazon Q Business web experience**

```
aws qbusiness delete-web-experience \
--application-id application-id \
--web-experience-id web-experience-id
```

------

## Getting properties of a web experience
<a name="describe-web-experience-iam"></a>

To get the properties of an Amazon Q Business web experience, you can use the console or the [GetWebExperience](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_GetWebExperience.html) API operation.

The following tabs provide a procedure for the AWS Management Console and code examples for the AWS CLI.

------
#### [ Console ]

**To get properties of an Amazon Q Business web experience ** 

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

1. In **Applications**, select the name of your application environment from the list of applications.

1. For **Web experience settings**, the following settings are available:
   + **Web experience IAM role ARN** – The IAM role assumed by end users when they log in to your web experience. 
   + **Deployed URL** – The deployed URL of your web experience. 
   + **Tags** – Tags that are attached to your web experience. 

   To update a setting, choose **Edit**.

------
#### [ AWS CLI ]

**To get properties of an Amazon Q Business web experience**

```
aws qbusiness get-web-experience \
--application-id application-id \
--web-experience-id web-experience-id
```

------

## Listing web experiences
<a name="list-web-experiences-iam"></a>

To list Amazon Q Business web experiences, you can use the console or the [ListWebExperiences](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListWebExperiences.html) API operation.

If you use the console, you can only see the web experience that's attached to a single application environment.

The following tabs provide a procedure for the AWS Management Console and code examples for the AWS CLI.

------
#### [ Console ]

**To list Amazon Q Business web experiences**

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

1. For **Applications**, the Amazon Q Business web experience attached to your application environment is shown.

------
#### [ AWS CLI ]

**To list Amazon Q Business web experiences**

```
aws qbusiness get-web-experience \
--application-id application-id \
--web-experience-id web-experience-id \
--max-results max-results-to-return
```

------

## Updating a web experience
<a name="update-web-experience-idp-iam"></a>

To update an Amazon Q Business web experience, you can use the console or the [UpdateWebExperience](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateWebExperience.html) API operation.

The following tabs provide a procedure for the AWS Management Console and code examples for the AWS CLI.

------
#### [ Console ]

**To update an Amazon Q Business web experience**

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

1. In **Applications**, select the name of your application environment from the list of applications.

1. Select **Customize web experience**.

1. Expand the right navigation menu to edit your web experience settings.

------
#### [ AWS CLI ]

**To update an Amazon Q Business web experience**

```
aws qbusiness update-web-experience \
--application-id application-id \
--web-experience-id web-experience-id \
--authentication-configuration authentication-configuration \  
--sample-prompts-control-mode sample-prompts \      
--subtitle subtitle \     
--title title \
--welcome-message welcome-message
```

------

# Managing subscriptions for applications using IAM Federation
<a name="manage-user-subscriptions-iam"></a>

To manage user subscriptions added to an application environment, you can perform the following actions:

**Topics**
+ [Updating subscription tiers](#update-user-subscriptions-tier-iam)
+ [Unsubscribing a user](#delete-user-subscriptions-iam)
+ [Listing user subscriptions](#list-user-subscriptions-iam)

## Updating subscription tiers
<a name="update-user-subscriptions-tier-iam"></a>

You can update a subscription tier using the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateSubscription.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateSubscription.html) API operation.

Amazon Q Business automatically assigns subscriptions to users in an IAM-federated application. You can update the auto-subscription tier for your application. When you update the auto-subscription tier for the Amazon Q Business application, the new tier applies to new users logging into your web experience. Existing subscription types assigned to users don't get updated when you update your subscription tier.

You can also update the subscription tier for specific users already assigned subscriptions.

For more information on user subscriptions for an IAM federated Amazon Q Business application, see [Subscriptions for applications using IAM Federation](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tiers.html#managing-sub-tiers-iam).

------
#### [ Console ]

**To update auto-subscription tier for an Amazon Q Business application** 

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

1. In **Applications**, select the name of the application environment that your uploaded files belong to.

1. From your applications page, select **Application settings**, and then select **Edit**.

1. From **Update application**, under **Default subscription settings**, in **Subscription tier**, choose between **Q Business Pro** and **Q Business Lite**.

1. Select **Update**.

**To update a specific user's subscription** 

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

1. In **Applications**, select the name of the application environment.

1. From your applications page, select **User access** and then select **Manage user access**.

1. On the **Manage access and subscriptions** page, from **Users**, select the user whose subscription you want to change and then select **Edit subscription**.

1. From the **Confirm subscription change** dialog box, from **New subscription**, and choose a new subscription tier.

1. Then, select **Confirm**.

1. On the **Manage access and subscriptions** page, select **Confirm** again.

------
#### [ AWS CLI ]

**To update user or group subscriptions**

```
aws qbusiness update-subscription \
--application-id application-id \
--subscription-id subscription-id \
--type subscription-type
```

------

## Unsubscribing a user
<a name="delete-user-subscriptions-iam"></a>

When you remove a user, it cancels their subscription. The user continues to be visible in the list of users till the end of the month, after which they're removed from the list. An unsubscribed user can continue to use the application until the end of the month on their canceled subscription.

You can choose to re-activate and re-assign a subscription to an inactive user from the subscriptions list. When an unsubscribed user re-logs into a Amazon Q Business application, Amazon Q Business automatically re-assigns them a subscription based on the active subscription tier for your application. However, an unsubscribed user can continue to use the application until the end of the month of their canceled subscription. So, if they start re-using Amazon Q Business in the same month their subscription is canceled, they will keep the same subscription tier they were originally assigned during that month. You must cancel a subscription for a user removed from your identity provider to stop subscription charges for them.

If an unsubscribed user wants to maintain the subscription beyond the first month, and they start using Amazon Q Business again next month, then they will get assigned the default subscription tier of their application (which could be a different subscription tier than the one they were assigned originally).

------
#### [ Console ]

**To unsubscribe a user from an Amazon Q Business application environment**

1. From your Amazon Q Business application home page, scroll down to the **Users** section, select **Manage user access**.

1. On the **Manage subscriptions** page, from **Users**, select **Remove**.

1. From the **Unsubscribe and remove** box, choose **Done**.

------
#### [ AWS CLI ]

**To cancel user or group subscriptions to Amazon Q Business**

```
aws qbusiness cancel-subscription \
--application-id application-id \
--subscription-id subscription-id \
--type subscription-type
```

------

## Listing user subscriptions
<a name="list-user-subscriptions-iam"></a>

To see a list of user and group subscriptions within a specific Amazon Q Business application, you can use the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListSubscriptions.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListSubscriptions.html) API operation.

For a consolidated view of your user subscriptions—including a list of subscribed users, their subscription status, and applications, accounts, or services a user can access through their subscriptions—you can also view the [Amazon Q subscriptions page](https://console.aws.amazon.com/amazonq/subscriptions).

------
#### [ Console ]

**To view a list of user and group subscriptions in an Amazon Q Business application environment**

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

1. In **Applications**, select the name of the application environment you created.

1. From your applications page, from the **User access** section, select **Manage user access**.

1. In the **Manage access and subscriptions** select **Users** if you want to view user subscriptions or **Groups** if you want to list group subscriptions.

**To view a consolidated list of all user and group subscriptions across all Amazon Q Business application environments**

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

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

1. From the left navigation menu, choose **Subscriptions**,and then select **Users** if you want to view user subscriptions or **Groups** if you want to list group subscriptions.

------
#### [ AWS CLI ]

**To list user or group subscriptions in an Amazon Q Business application**

```
aws qbusiness list-subscriptions \
--application-id application-id
```

**To list user or group subscriptions across all Amazon Q Business applications**

This action is not supported.

------

# Tagging resources in Amazon Q Business
<a name="tagging-iam"></a>

Manage your Amazon Q Business applications and data sources by assigning tags. You can use tags to categorize your Amazon Q Business resources in various ways. For example, you could categorize by purpose, owner, or application, or any combination. Each tag consists of a *key* and a *value*, both of which you define.

Tags help you to do the following:
+ **Identify and organize your AWS resources** – Many AWS services support tagging, so you can assign the same tag to resources in different services to indicate that the resources are related. For example, you can tag an Amazon Kendra retriever and the Amazon Q Business web experience that uses the retriever with the same tag.
+ **Allocate costs** – You activate tags on the AWS Billing and Cost Management dashboard. AWS uses tags to categorize your costs and deliver a monthly cost allocation report to you. For more information, see [Cost Allocation and Tagging](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/cost-alloc-tags.html) in the *AWS Billing User Guide*.
+ **Control access to your resources** – You can use tags in AWS Identity and Access Management (IAM) policies that control access to Amazon Q Business resources. To activate tag-based access control, you can attach these policies to an IAM role or IAM user. For more information, see [Authorization based on tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/security_iam_service-with-iam.html#security_iam_service-with-iam-tags).

You can create and manage tags using the AWS Management Console, the AWS Command Line Interface (AWS CLI), or the Amazon Q Business API.

**Topics**
+ [Using tags](#tagging-resources-iam)
+ [Tag restrictions](#tag-restrictions-iam)

## Using tags
<a name="tagging-resources-iam"></a>

If you're using the console, you can tag resources when you create them or add them later. You can also use the console to update or remove tags in the following ways:

------
#### [ Adding tags ]

**To add Amazon Q Business tags**

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

1. From **Applications**, select the application whose resources you want to tag.

1. From the application summary page, scroll down and select **Tags**.

1. In **Tags**, from the resource you want to add tags to, select **Manage tags**.

1. In **Tags – *optional***, select **Add new tag** to add tags to your Amazon Q Business resource. Then, enter the following information for each tag:
   + **Key** – Add a key for your tag.
   + **Value - *optional*** – An optional value for your tag.

1. Select **Save**.

------
#### [ Removing tags ]

**To remove tags**

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

1. From **Applications**, select the application you want to delete tags from.

1. From the application summary page, scroll down and select **Tags**.

1. In **Tags**, from the resource you want to add tags to, select **Manage tags**.

1. In **Tags – *optional***, select **Remove**.

1. Select **Save**.

------
#### [ Listing tags ]

**To view a list of tags**

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

1. From **Applications**, select the application you want to delete tags from.

1. From the application summary page, scroll down and select **Tags**.

1. In **Tags**, each tagged resource will display a list of tags associated with it.

------

If you're using the AWS CLI or the Amazon Q Business API, use the following operations to manage tags for your resources:
+ [CreateApplication](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateApplication.html) – Apply tags when you create an Amazon Q Business application.
+ [CreateWebExperience](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateWebExperience.html) – Apply tags when you create an Amazon Q Business web experience.
+ [ListTagsForResource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListTagsForResource.html) – View the tags associated with a resource.
+ [TagResource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_TagResource.html) – Add and modify tags for a resource.
+ [UntagResource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UntagResource.html) – Remove tags from a resource.

## Tag restrictions
<a name="tag-restrictions-iam"></a>

The following restrictions apply to tags on Amazon Q Business resources:
+ Maximum number of tags – 50
+ Maximum key length – 128 characters
+ Maximum value length – 256 characters
+ Valid characters for key and value – a–z, A–Z, space, and the following characters: \$1 . : / = \$1 - and @
+ Keys and values are case sensitive
+ Don't use `aws:` as a prefix for keys; it's reserved for AWS use