Filtering on user context

You can filter a user's search results based on the user or their group access to documents. You can use a user token, user ID, or user attribute to filter documents.

User context filtering is a kind of personalized search with the benefit of controlling access to documents. For example, not all teams that search the company portal for information should access top-secret company documents, nor are these documents relevant to all users. Only specific users or groups of teams given access to top-secret documents should see these documents in their search results.

When a document is indexed into Amazon Kendra, a corresponding access control list (ACL) is ingested for most documents. The ACL specifies which user names and group names are allowed or denied access to the document. Documents without an ACL are public documents.

Amazon Kendra can extract the user or group information associated with each document for most data sources. For example, a document in Quip can include a 'share' list of select users that are given access to the document. If you use an S3 bucket as a data source, you provide a JSON file for your ACL and include the S3 path to this file as part of the data source configuration. If you add documents directly to an index, you specify the ACL in the Principal object as part of the document object in the BatchPutDocument API.

If you're using an Amazon Kendra Enterprise or Developer Edition index, you can use the CreateAccessControlConfiguration API to re-configure your existing document level access control without indexing all of your documents again. For example, your index contains top-secret company documents that only certain employees or users should access. One of these users leaves the company or switches to a team that should be blocked from accessing top-secret documents. The user still has access to top-secret documents because the user had access when your documents were previously indexed. You can create a specific access control configuration for the user with deny access. You can later update the access control configuration to allow access in the case the user returns to the company and re-joins the 'top-secret' team. You can re-configure access control for your documents as circumstances change.

To apply your access control configuration to certain documents, you call the BatchPutDocument API with the AccessControlConfigurationId included in the Document object. If you use an S3 bucket as a data source, you update the .metadata.json with the AccessControlConfigurationId and synchronize your data source. Amazon Kendra currently only supports access control configuration for S3 data sources and documents indexed using the BatchPutDocument API.

Filtering by user token

When you query an index, you can use a user token to filter search results based on the user or their group access to documents. When you issue a query, Amazon Kendra extracts and validates the token, pulls and checks the user and group information, and runs the query. All of the documents the user has access to, including public documents, are returned. For more information, see Token-based user access control.

You provide the user token in the UserContext object and pass this in the Query API.

The following shows how to include a user token.

response = kendra.query(
    QueryText = query,
    IndexId = index,
    UserToken = {
        Token = "token"
    })

You can map users to groups. When you use user-context filtering, it is not required to include all of the groups that a user belongs to when you issue the query. With the PutPrincipalMapping API, you can map users to their groups. If you do not want to use the PutPrincipalMapping API, you must provide the user name and all the groups the user belongs to when you issue a query. You can also fetch access levels of groups and users in your IAM Identity Center identity source by using the UserGroupResolutionConfiguration object.

Filtering by user ID and group

When you query an index, you can use the user ID and group to filter search results based on the user or their group access to documents. When you issue a query, Amazon Kendra checks the user and group information and runs the query. All of the documents relevant to the query that the user has access to, including public documents, are returned.

You can also filter search results by data sources that users and groups have access to. Specifying a data source is useful if a group is tied to multiple data sources, but you only want the group to access documents of a certain data source. For example, the groups "Research", "Engineering", and "Sales and Marketing" are all tied to the company's documents stored in the data sources Confluence and Salesforce. However, "Sales and Marketing" team only needs access to customer-related documents stored in Salesforce. So when sales and marketing users search for customer-related documents, they can see documents from Salesforce in their results. Users who do not work in sales and marketing do not see Salesforce documents in their search results.

You provide the user, groups and data sources information in the UserContext object and pass this in the Query API. The user ID, and the list of groups and data sources should match the name you specify in the Principal object to identify the user, groups, and data sources. With the Principal object, you can add a user, group, or data source to either an allow list or a deny list for accessing a document.

You are required to provide one of the following:

If this information is not included in the query, Amazon Kendra returns all documents. If you provide this information, only documents with matching user IDs, groups, and data sources are returned.

The following shows how to include user ID, groups, and data sources.

response = kendra.query(
    QueryText = query,
    IndexId = index,
    UserContext={'Token': 'string', 'UserId': 'string', 'Groups': [ 'string', ], 'DataSourceGroups': [ { 'GroupId': 'string', 'DataSourceId': 'string' }, ] },)

Filtering by user attribute

When you query an index, you can use built-in attributes _user_id and _group_id to filter search results based on the user and their group access to documents. You can set up to 100 group identifiers. When you issue a query, Amazon Kendra checks the user and group information and runs the query. All documents relevant to the query that the user has access to, including public documents, are returned.

You provide the user and group attributes in the AttributeFilter object and pass this in the Query API.

The following example shows a request that filters the query response based on the user ID and the groups "HR" and "IT", which the user belongs to. The query will return any document that has the user or the "HR" or "IT" groups in the allow list. If the user or either group is in the deny list for a document, the document is not returned.

response = kendra.query(
        QueryText = query,
        IndexId = index,
        AttributeFilter = {
            "OrAllFilters": [
                {
                    "EqualsTo": {
                        "Key": "_user_id",
                        "Value": {
                            "StringValue": "user1"
                        }
                     }
                },
                {
                    "EqualsTo": {
                        "Key": "_group_ids",
                        "Value": {
                            "StringListValue": ["HR", "IT"]
                        }
                    }
                }
            ]
        }
        )

You can also specify which data source a group can access in the Principal object.

There is an implementation of user context filtering for each data source. The following section describes each implementation.

User context filtering for documents added directly to an index

When you add documents directly to an index using the BatchPutDocument API, Amazon Kendra gets user and group information from the AccessControlList field of the document. You provide an access control list (ACL) for your documents and the ACL is ingested with your documents.

You specify the ACL in the Principal object as part of the Document object in the BatchPutDocument API. You provide the following information:

You can add up to 200 entries in the AccessControlList field.

User context filtering for frequently asked questions

When you add a FAQ to an index, Amazon Kendra gets user and group information from the AccessControlList object/field of the FAQ JSON file. You can also use a FAQ CSV file with custom fields or attributes for access control.

You provide the following information:

For more information, see FAQ files.

User context filtering for data sources

Amazon Kendra also crawls user and group access control list (ACL) information from supported data source connectors. This is useful for user context filtering, where search results are filtered based on the user or their group access to documents.

User context filtering for Adobe Experience Manager data sources

When you use an Adobe Experience Manager data source, Amazon Kendra gets the user and group information from the Adobe Experience Manager instance.

The group and user IDs are mapped as follows:

You can add up to 200 entries in the AccessControlList field.

User context filtering for Alfresco data sources

When you use an Alfresco data source, Amazon Kendra gets the user and group information from the Alfresco instance.

The group and user IDs are mapped as follows:

You can add up to 200 entries in the AccessControlList field.

User context filtering for Aurora (MySQL) data sources

When you use a Aurora (MySQL) data source, Amazon Kendra gets user and group information from a column in the source table. You specify this column in the console or using the TemplateConfiguration object as part of the CreateDataSource API.

A Aurora (MySQL) database data source has the following limitations:

User context filtering for Aurora (PostgreSQL) data sources

When you use a Aurora (PostgreSQL) data source, Amazon Kendra gets user and group information from a column in the source table. You specify this column in the console or using the TemplateConfiguration object as part of the CreateDataSource API.

A Aurora (PostgreSQL) database data source has the following limitations:

User context filtering for Amazon FSx data sources

When you use an Amazon FSx data source, Amazon Kendra gets user and group information from the directory service of the Amazon FSx instance.

The Amazon FSx group and user IDs are mapped as follows:

You can add up to 200 entries in the AccessControlList field.

User context filtering for database data sources

When you use a database data source, such as Amazon Aurora PostgreSQL, Amazon Kendra gets user and group information from a column in the source table. You specify this column in the AclConfiguration object as part of the DatabaseConfiguration object in the CreateDataSource API.

A database data source has the following limitations:

User context filtering for Amazon RDS (Microsoft SQL Server) data sources

When you use a Amazon RDS (Microsoft SQL Server) data source, Amazon Kendra gets user and group information from a column in the source table. You specify this column in the console or using the TemplateConfiguration object as part of the CreateDataSource API.

A Amazon RDS (Microsoft SQL Server) database data source has the following limitations:

User context filtering for Amazon RDS (MySQL) data sources

When you use a Amazon RDS (MySQL) data source, Amazon Kendra gets user and group information from a column in the source table. You specify this column in the console or using the TemplateConfiguration object as part of the CreateDataSource API.

A Amazon RDS (MySQL) database data source has the following limitations:

User context filtering for Amazon RDS (Oracle) data sources

When you use a Amazon RDS (Oracle) data source, Amazon Kendra gets user and group information from a column in the source table. You specify this column in the console or using the TemplateConfiguration object as part of the CreateDataSource API.

A Amazon RDS (Oracle) database data source has the following limitations:

User context filtering for Amazon RDS (PostgreSQL) data sources

When you use a Amazon RDS (PostgreSQL) data source, Amazon Kendra gets user and group information from a column in the source table. You specify this column in the console or using the TemplateConfiguration object as part of the CreateDataSource API.

A Amazon RDS (PostgreSQL) database data source has the following limitations:

User context filtering for Amazon S3 data sources

You add user context filtering to a document in an Amazon S3 data source using a metadata file associated with the document. You add the information to the AccessControlList field in the JSON document. For more information about adding metadata to the documents indexed from an Amazon S3 data source, see S3 document metadata.

You provide three pieces of information:

You can add up to 200 entries in the AccessControlList field.

User context filtering for Amazon WorkDocs data sources

When you use an Amazon WorkDocs data source, Amazon Kendra gets user and group information from the Amazon WorkDocs instance.

The Amazon WorkDocs group and user IDs are mapped as follows:

You can add up to 200 entries in the AccessControlList field.

User context filtering for Box data sources

When you use a Box data source, Amazon Kendra gets user and group information from the Box instance.

The Box group and user IDs are mapped as follows:

You can add up to 200 entries in the AccessControlList field.

User context filtering for Confluence data sources

When you use a Confluence data source, Amazon Kendra gets user and group information from the Confluence instance.

You configure user and group access to spaces using the space permissions page. For pages and blogs, you use the restrictions page. For more information about space permissions, see Space Permissions Overview on the Confluence Support website. For more information about page and blog restrictions, see Page Restrictions on the Confluence Support website.

The Confluence group and user names are mapped as follows:

You can add up to 200 entries in the AccessControlList field.

User context filtering for Dropbox data sources

When you use a Dropbox data source, Amazon Kendra gets the user and group information from the Dropbox instance.

The group and user IDs are mapped as follows:

You can add up to 200 entries in the AccessControlList field.

User context filtering for Drupal data sources

When you use a Drupal data source, Amazon Kendra gets the user and group information from the Drupalinstance.

The group and user IDs are mapped as follows:

You can add up to 200 entries in the AccessControlList field.

User context filtering for GitHub data sources

When you use a GitHub data source, Amazon Kendra gets user information from the GitHub instance.

The GitHub user IDs are mapped as follows:

You can add up to 200 entries in the AccessControlList field.

User context filtering for Gmail data sources

When you use a Gmail data source, Amazon Kendra gets the user information from the Gmail instance.

The user IDs are mapped as follows:

You can add up to 200 entries in the AccessControlList field.

User context filtering for Google Drive data sources

A Google Workspace Drive data source returns user and group information for Google Drive users and groups. Group and domain membership are mapped to the _group_ids index field. The Google Drive user name is mapped to the _user_id field.

When you provide one or more user email addresses in the Query API, only documents that have been shared with those email addresses are returned. The following AttributeFilter parameter only returns documents shared with "martha@example.com".

"AttributeFilter": {
                "EqualsTo":{
                   "Key": "_user_id", 
                   "Value": {
                       "StringValue": "martha@example.com"
                   }
               }
           }

If you provide one or more group email addresses in the query, only documents shared with the groups are returned. The following AttributeFilter parameter only returns documents shared with the "hr@example.com" group.

"AttributeFilter": {
                "EqualsTo":{
                   "Key": "_group_ids", 
                   "Value": {
                       "StringListValue": ["hr@example.com"]
                   }
               }
           }

If you provide the domain in the query, all documents shared with the domain are returned. The following AttributeFilter parameter returns documents shared with the "example.com" domain.

"AttributeFilter": {
                "EqualsTo":{
                   "Key": "_group_ids", 
                   "Value": {
                       "StringListValue": ["example.com"]
                   }
               }
           }

You can add up to 200 entries in the AccessControlList field.

User context filtering for IBM DB2 data sources

When you use a IBM DB2 data source, Amazon Kendra gets user and group information from a column in the source table. You specify this column in the console or using the TemplateConfiguration object as part of the CreateDataSource API.

A IBM DB2 database data source has the following limitations:

User context filtering for Jira data sources

When you use a Jira data source, Amazon Kendra gets user and group information from the Jira instance.

The Jira user IDs are mapped as follows:

You can add up to 200 entries in the AccessControlList field.

User context filtering for Microsoft Exchange data sources

When you use a Microsoft Exchange data source, Amazon Kendra gets the user information from the Microsoft Exchange instance.

The Microsoft Exchange user IDs are mapped as follows:

You can add up to 200 entries in the AccessControlList field.

User context filtering for Microsoft OneDrive data sources

Amazon Kendra retrieves user and group information from Microsoft OneDrive when it indexes the documents on the site. The user and group information is taken from the underlying Microsoft SharePoint site that hosts OneDrive.

When you use a OneDrive user or group for filtering search results, calculate the ID as follows:

Send the user or group ID to Amazon Kendra as the _user_id or _group_id attribute when you call the Query API. For example, the AWS CLI command that uses a group to filter the search results looks like this:

aws kendra  query \
                --index-id index ID  
                --query-text "query text" 
                --attribute-filter '{
                   "EqualsTo":{
                     "Key": "_group_id", 
                     "Value": {"StringValue": "430a6b90503eef95c89295c8999c7981 | localGroupName"}
                  }}'

You can add up to 200 entries in the AccessControlList field.

User context filtering for Microsoft OneDrive v2.0 data sources

A Microsoft OneDrive v2.0 data source returns section and page information from OneDrive access control list (ACL) entities. Amazon Kendra uses the OneDrive tenant domain to connect to the OneDrive instance and then can filter search results based on user or group access to sections and file names.

For standard objects, the _user_id and _group_id are used as follows:

You can add up to 200 entries in the AccessControlList field.

User context filtering for Microsoft SharePoint data sources

Amazon Kendra retrieves user and group information from Microsoft SharePoint when it indexes the site documents. To filter search results based on user or group access, provide user and group information when you call the Query API.

To filter using a user name, use the user's email address. For example, johnstiles@example.com.

When you use a SharePoint group for filtering search results, calculate the group ID as follows:

For local groups

Send the group ID to Amazon Kendra as the _group_id attribute when you call the Query API. For example, the AWS CLI command looks like this:

aws kendra  query \
                --index-id index ID  
                --query-text "query text" 
                --attribute-filter '{
                   "EqualsTo":{
                     "Key": "_group_id", 
                     "Value": {"StringValue": "430a6b90503eef95c89295c8999c7981 | localGroupName"}
                  }}'

For AD groups

Send the group ID to Amazon Kendra as the _group_id attribute when you call the Query API. For example, the AWS CLI command looks like this:

aws kendra  query \
                --index-id index ID  
                --query-text "query text" 
                --attribute-filter '{
                   "EqualsTo":{
                     "Key": "_group_id", 
                     "Value": {"StringValue": "AD group"}
                  }}'

You can add up to 200 entries in the AccessControlList field.

User context filtering for Microsoft SQL Server data sources

When you use a Microsoft SQL Server data source, Amazon Kendra gets user and group information from a column in the source table. You specify this column in the console or using the TemplateConfiguration object as part of the CreateDataSource API.

A Microsoft SQL Server database data source has the following limitations:

User context filtering for Microsoft Teams data sources

Amazon Kendra retrieves user information from Microsoft Teams when it indexes the documents. The user information is taken from the underlying Microsoft Teams instance.

You can add up to 200 entries in the AccessControlList field.

User context filtering for Microsoft Yammer data sources

Amazon Kendra retrieves user information from Microsoft Yammer when it indexes the documents. The user and group information is taken from the underlying Microsoft Yammer instance.

The Microsoft Yammer user IDs are mapped as follows:

You can add up to 200 entries in the AccessControlList field.

User context filtering for MySQL data sources

When you use a MySQL data source, Amazon Kendra gets user and group information from a column in the source table. You specify this column in the console or using the TemplateConfiguration object as part of the CreateDataSource API.

A MySQL database data source has the following limitations:

User context filtering for Oracle Database data sources

When you use a Oracle Database data source, Amazon Kendra gets user and group information from a column in the source table. You specify this column in the console or using the TemplateConfiguration object as part of the CreateDataSource API.

A Oracle Database database data source has the following limitations:

User context filtering for PostgreSQL data sources

When you use a PostgreSQL data source, Amazon Kendra gets user and group information from a column in the source table. You specify this column in the console or using the TemplateConfiguration object as part of the CreateDataSource API.

A PostgreSQL database data source has the following limitations:

User context filtering for Quip data sources

When you use a Quip data source, Amazon Kendra gets the user information from the Quip instance.

The Quip user IDs are mapped as follows:

You can add up to 200 entries in the AccessControlList field.

User context filtering for Salesforce data sources

A Salesforce data source returns user and group information from Salesforce access control list (ACL) entities. You can apply user context filtering to Salesforce standard objects and chatter feeds. User context filtering is not available for Salesforce knowledge articles.

If you map any Salesforce field to Amazon Kendra document title and document body fields, Amazon Kendra will use data from the document title and body fields in search responses.

For standard objects, the _user_id and _group_ids are used as follows:

For chatter feeds, the _user_id and _group_ids are used as follows:

You can add up to 200 entries in the AccessControlList field.

User context filtering for ServiceNow data sources

User context filtering for ServiceNow is supported only for the TemplateConfiguration API and ServiceNow Connector v2.0. ServiceNowConfiguration API and ServiceNow Connector v1.0. do not support user context filtering.

When you use a ServiceNow data source, Amazon Kendra gets the user and group information from the ServiceNow instance.

The group and user IDs are mapped as follows:

You can add up to 200 entries in the AccessControlList field.

User context filtering for Slack data sources

When you use a Slack data source, Amazon Kendra gets the user information from the Slack instance.

The Slack user IDs are mapped as follows:

You can add up to 200 entries in the AccessControlList field.

User context filtering for Zendesk data sources

When you use a Zendesk data source, Amazon Kendra gets the user and group information from the Zendesk instance.

The group and user IDs are mapped as follows:

You can add up to 200 entries in the AccessControlList field.