# Understanding Amazon Q Business User Store
Understanding User Store

With the Amazon Q Business *User Store* feature, end users see Amazon Q Business chat responses generated *only* from the documents that they have access to within an Amazon Q Business application. To achieve this, Amazon Q creates a mapping within the data sources attached to that application. The mapping is between every unique user accessing the application environment and all the user IDs and user groups that they are associated with. Amazon Q Business stores this principal mapping information in its internal User Store. During chat, Amazon Q Business uses the mapping information to return answers that are scoped to a user’s identity.

When you use the API, you use the User Store API actions to customize and configure your user management solution. For more details, see [Using User Store APIs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/principal-store-hiw.html#principal-store-hiw-api).

When you use the console, Amazon Q Business automatically crawls user and group information during the connector setup process. You can't create, add, or customize users and groups to the user store using the AWS Management Console.

**Note**  
As of Dec 17, 2024, Amazon Q Business will recognize all email addresses as case-insensitive and recognize subaddresses as equivalent to the original email address. For example, JohnDoe@example.com, johndoe@example.com, and johndoe\$1work@example.com will be considered the same email address. For assistance with applications or to report a concern, contact Support sign into the [AWS Support Center](https://console.aws.amazon.com/support/home#/) .

**Note**  
The User Store feature is not available for the Amazon S3 and Amazon Q Web Crawler connectors that are used with Amazon Q Business. For more information about using access control information for user identity specific chat responses for these connectors, see [Amazon S3](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/s3-connector.html#s3-user-management) and [Amazon Q Business Web Crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-webcrawler.html). 

**Topics**
+ [

# Principal mapping
](principal-mapping.md)
+ [

# How the User Store works
](principal-store-hiw.md)

# Principal mapping


Amazon Q Business uses *principal mapping* to map users and groups with permissions to access an Amazon Q Business application environment to their user ids and group membership information within the data sources that are connected to the application.

Although user and group mapping is a synchronous, simultaneous process, the following sections explain them separately for conceptual clarity.

**Topics**
+ [

## User mapping
](#user-mapping)
+ [

## Group mapping
](#group-mapping)

## User mapping


Each Amazon Q Business application environment can have multiple data sources connected to it. Each data source can have specific users and groups configured within it. Additionally, a user can be associated with multiple groups within a data source, or be attached to multiple groups across multiple data sources. A user attached to multiple data sources can also have different user IDs within these data sources.

A unique end user who signs in to an Amazon Q Business application environment must see only chat responses generated from documents that they have access to. To achieve that objective, Amazon Q Business maps their user IDs and group IDs within each data source to their identity provider (IdP) login credentials. Then, Amazon Q Business creates a universally unique identifier (UUID) to assign to each user. Using the UUID that it creates, Amazon Q Business stores a comprehensive mapping of the user’s group membership in an application. During chat, Amazon Q Business checks this UUID that's stored in its user store and retrieves user access information to generate chat responses. 

The User Store feature also supports the following user management scenarios:
+ **An end user leaves your organization.**

  When an end user leaves your organization, you can choose to delete the user from your user store.
+ **An end user leaves your organization, and their email gets reassigned.**

  Because the User Store assigns each user a UUID for secure and accurate chat responses, using an email reassigned from a previous UUID to a new one doesn't impact the content that a user sees. Any new user within your application environment that is using a reassigned email ID will be assigned a new UUID to be used for response generation.
+ **An end user with multiple login IDs needs chat content generated from documents they access using both these login IDs.**

  With User Store, you can store user aliases attached to end user UUIDs. For example, a username Saanvi Sarkar uses two login IDs to sign in to Amazon Q Business—`saanvi_sarkar` and `saanvi_s`. You can store both IDs under the same UUID to ensure their chat responses are generated from content that they access using both login IDs.

## Group mapping


Each Amazon Q Business application environment can have multiple data sources attached to it. Each data source in an Amazon Q Business application environment can have multiple groups attached to it. Multiple groups can repeat across multiple data sources. Additionally, each group across data sources can also contain multiple subgroups. Each Amazon Q Business application environment also has an associated identity provider (IdP) that can contain group information for the users accessing the application.

A unique end user signing in to an Amazon Q Business application environment must see only chat responses generated from documents within groups that they have access to. To achieve that objective, Amazon Q Business does the following:
+ Automatically crawls local groups and their associated relationships from data sources during the connector configuration process.
+ Provides you with API operations to map your end users group and subgroup membership details within each data source to their IdP group membership.

**Note**  
As of Dec 17, 2024, Amazon Q Business will recognize all email addresses as case-insensitive and recognize subaddresses as equivalent to the original email address. For example, JohnDoe@example.com, johndoe@example.com, and johndoe\$1work@example.com will be considered the same email address. For assistance with applications or to report a concern, contact Support, sign into the [AWS Support Center](https://console.aws.amazon.com/support/home#/) .

Then, Amazon Q Business creates a unique user identifier (UUID) to assign to each user. Under the UUID, Amazon Q Business stores a comprehensive mapping of the user’s group membership in an application. During chat, Amazon Q Business checks this UUID that's stored in its user store and quickly retrieves group access information to generate chat responses.

The User Store feature supports the following group management scenarios:
+ **Your users mapped to all groups that they have access to within an Amazon Q Business application.**

  Amazon Q Business crawls all groups that a user has access to in a data source and stores this information under a user's UUID.
+ **Create a subgroup of users within your application.**

  For example, for a group called `company_employees`, you might want to create a subgroup `summer_interns` and specify group level access for the subgroup. You might also want to group your interns into further subgroups like `product_interns` and `engineering_interns`.
+ **Map your data source groups to your IdP groups.**

  A unique end user signing in to an Amazon Q Business application must see only chat responses generated from documents within groups they have access to. To support that objective, you can use Amazon Q to map your end users group membership details within each data source to their IdP group membership.
**Note**  
Amazon Q Business doesn't interact or crawl this information from your IdP automatically. To ingest the relationship between data source groups and IdP groups, use the Amazon Q Business API.

# How the User Store works


Each document in any data source has access control list (ACL) information inherently attached to it as metadata. ACLs contain information about which users and groups have access to a document.

Connectors support crawl ACL and identity information where applicable based on the data source. To index documents without ACLs (as public documents) ensure the documents you want to index from your data source are public documents in the enterprise data source the connectors index the content from.

An Amazon Q Business connector updates any changes in ACLs each time that your data source content is crawled. To capture ACL changes to make sure that the right end users have access to the right content, re-sync your data source regularly.

**Note**  
As of Dec 17, 2024, Amazon Q Business will recognize all email addresses as case-insensitive and recognize subaddresses as equivalent to the original email address. For example, JohnDoe@example.com, johndoe@example.com, and johndoe\$1work@example.com will be considered the same email address. For assistance with applications or to report a concern, contact Support, sign into the [AWS Support Center](https://console.aws.amazon.com/support/home#/) .

**Note**  
Amazon Q Business supports crawling ACLs for document security by default. As a general rule, turning off ACLs and identity crawling once they have been enabled are no longer supported. In preparation for [connecting Amazon Q Business applications to IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/migrate-application.html), enable ACL indexing and identity crawling for secure querying and re-sync your connector. Once you turn ACL and identity crawling on you won't be able to turn them off. Certain connectors provide you with the ability to manage ACLs by enabling or disabling them during data source creation. To create a data source with ACLs disabled, you need specific IAM permissions. For more information, see [Setting up](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html).

Each data source also contains information about the users and groups which have access to it. Amazon Q Business crawls information about users and groups attached to each data source and automatically extracts and maps user and group information internally. Amazon Q Business then stores this crawled identity information in the user store and uses it to match and map user and group IDs with their document access details.

If you delete a group in the User Store and then re-create it later with the same name but with different group members, document ACLs which contain this group may be impacted. We recommend that this type of change (deleting or re-creating a group with the same name but with different group members) be done in the data source instead of the Amazon Q Business User Store.

Using a reassigned email address requires deleting the original user’s UUID from the User Store. This is because Amazon Q Business verifies that the new user's IAM Identity Center attributes match those in the User Store. If the previous email address user UUID is not deleted, and the previous user’s attributes are found, API calls will be denied.

**Important**  
Inadvertent mistakes when you update the User Store’s user, group, group membership, and mapping information can result in unintentional and unacceptable changes in the accessibility of documents to users.  
Treat the ability to update the User Store to create users, update users, delete users, create groups, update groups, delete groups (i.e, create update delete operations), and update the mappings, as a privileged operation.  
Ensure that access to the User Store APIs is provided only to admin who fully understand how to use these APIs and the implications of these changes on your document security. We recommend establishing a documented approval process be followed for making such changes. 

The following overview describes how principal mapping works by using either the console or the Amazon Q Business API.

**Topics**
+ [

## Using the console
](#principal-store-hiw-console)
+ [

## Using the API
](#principal-store-hiw-api)

## Using the console


Each document in any data source has access control list (ACL) information inherently attached to it as metadata. ACLs contain information about which users and groups have access to a document. To ensure document security, Amazon Q Business crawls ACL information by default. Then, the connector automatically extracts and maps document access information internally.

When you crawl this ACL information, Amazon Q Business stores it in its internal user store to assess which user IDs have access to a document.

Each data source also contains information about the users and groups which have access to it. During data source connector configuration, Amazon Q Business crawls information about users and groups attached to each data source. Then, the connector automatically extracts and maps user and group information internally.

Amazon Q Business stores this crawled identity information in the user store and uses it to match and map user and group ids with their document access details. You can only use the **Identity crawler** feature if you also crawl ACLs using the **Authorization** feature.

If you use the console, you must re-sync your data to your index to capture any changes in the ACL and user and group membership within your data source. 

For more information regarding setting up user mapping for specific connectors, consult the detailed ACL crawling documentation section for that connector. For example, if you need to set up user mapping for Salesforce Online, see [How Amazon Q Business connector crawls Salesforce ACLs](salesforce-user-management.md).

## Using the API


When you configure your Amazon Q Business application, you use the following API operations to create your principal mapping solution:

**User management**
+ [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateUser.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateUser.html) – Creates a universally unique identifier (UUID) that's mapped to a list of local user IDs within a data source.
+ [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DeleteUser.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DeleteUser.html) — Deletes a UUID that's mapped to a user.
+ [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateUser.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateUser.html) – Updates local user IDs within a data source that are mapped to a UUID.
+ [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_GetUser.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_GetUser.html) – Lists information associated with a user ID.

**Group management**
+ [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_PutGroup.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_PutGroup.html) – Creates, or updates, a mapping of users to groups, or groups to subgroups. You can use this API operation to:
  + Map a group from groups in the data source to groups in your IdP.
  + Map a list of users and sub groups (for example, `Interns`) to a group (for example, `Interns 2023`).
+ [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DeleteGroup.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DeleteGroup.html) – Deletes a group or a subgroup.
+ [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_GetGroup.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_GetGroup.html) – Lists information about a group.