access_control_configurations

Creates, updates, deletes, gets or lists an access_control_configurations resource.

Overview

Name	access_control_configurations
Type	Resource
Id	aws.kendra.access_control_configurations

Fields

The following fields are returned by SELECT queries:

describe_access_control_configuration

Name	Datatype	Description
access_control_list	array	Information on principals (users and/or groups) and which documents they should have access to. This is useful for user context filtering, where search results are filtered based on the user or their group access to documents.
description	string	The description for the access control configuration. (pattern: <code>^\P{C}*$</code>)
error_message	string	The error message containing details if there are issues processing the access control configuration. (pattern: <code>^\P{C}*$</code>)
hierarchical_access_control_list	array	The list of principal lists that define the hierarchy for which documents users should have access to.
name	string	The name for the access control configuration. (pattern: <code>[\S\s]*</code>)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
describe_access_control_configuration	select	region		Gets information about an access control configuration that you created for your documents in an index. This includes user and group access information for your documents. This is useful for user context filtering, where search results are filtered based on the user or their group access to documents.
create_access_control_configuration	insert	region, IndexId		Creates an access configuration for your documents. This includes user and group access information for your documents. This is useful for user context filtering, where search results are filtered based on the user or their group access to documents. You can use this 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 if 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. You can't configure access control using CreateAccessControlConfiguration for an Amazon Kendra Gen AI Enterprise Edition index. Amazon Kendra will return a ValidationException error for a Gen_AI_ENTERPRISE_EDITION index.
update_access_control_configuration	update	region, IndexId		Updates an access control configuration for your documents in an index. This includes user and group access information for your documents. This is useful for user context filtering, where search results are filtered based on the user or their group access to documents. You can update an access control configuration you created without indexing all of your documents again. For example, your index contains top-secret company documents that only certain employees or users should access. You created an 'allow' access control configuration for one user who recently joined the 'top-secret' team, switching from a team with 'deny' access to top-secret documents. However, the user suddenly returns to their previous team and should no longer have access to top secret documents. You can update the access control configuration to re-configure access control for your documents as circumstances change. You call the BatchPutDocument API to apply the updated access control configuration, with the AccessControlConfigurationId included in the Document object. If you use an S3 bucket as a data source, you synchronize your data source to apply the AccessControlConfigurationId in the .metadata.json file. Amazon Kendra currently only supports access control configuration for S3 data sources and documents indexed using the BatchPutDocument API. You can't configure access control using CreateAccessControlConfiguration for an Amazon Kendra Gen AI Enterprise Edition index. Amazon Kendra will return a ValidationException error for a Gen_AI_ENTERPRISE_EDITION index.
delete_access_control_configuration	delete	region		Deletes an access control configuration that you created for your documents in an index. This includes user and group access information for your documents. This is useful for user context filtering, where search results are filtered based on the user or their group access to documents.
list_access_control_configurations	exec	region, IndexId		Lists one or more access control configurations for an index. This includes user and group access information for your documents. This is useful for user context filtering, where search results are filtered based on the user or their group access to documents.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
region	string	AWS region (default: us-east-1)

SELECT examples

describe_access_control_configuration

Gets information about an access control configuration that you created for your documents in an index. This includes user and group access information for your documents. This is useful for user context filtering, where search results are filtered based on the user or their group access to documents.

SELECT
access_control_list,
description,
error_message,
hierarchical_access_control_list,
name
FROM aws.kendra.access_control_configurations
WHERE region = '{{ region }}' -- required
;

INSERT examples

create_access_control_configuration

Creates an access configuration for your documents. This includes user and group access information for your documents. This is useful for user context filtering, where search results are filtered based on the user or their group access to documents. You can use this 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 if 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. You can't configure access control using CreateAccessControlConfiguration for an Amazon Kendra Gen AI Enterprise Edition index. Amazon Kendra will return a ValidationException error for a Gen_AI_ENTERPRISE_EDITION index.

INSERT INTO aws.kendra.access_control_configurations (
IndexId,
Name,
Description,
AccessControlList,
HierarchicalAccessControlList,
ClientToken,
region
)
SELECT 
'{{ IndexId }}' /* required */,
'{{ Name }}',
'{{ Description }}',
'{{ AccessControlList }}',
'{{ HierarchicalAccessControlList }}',
'{{ ClientToken }}',
'{{ region }}'
RETURNING
id
;

Manifest

# Description fields are for documentation purposes
- name: access_control_configurations
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the access_control_configurations resource.
  - name: IndexId
    value: "{{ IndexId }}"
    description: |
      The identifier of the index to create an access control configuration for your documents.
  - name: Name
    value: "{{ Name }}"
    description: |
      A name for the access control configuration.
  - name: Description
    value: "{{ Description }}"
    description: |
      A description for the access control configuration.
  - name: AccessControlList
    description: |
      Information on principals (users and/or groups) and which documents they should have access to. This is useful for user context filtering, where search results are filtered based on the user or their group access to documents.
    value:
      - Name: "{{ Name }}"
        Type: "{{ Type }}"
        Access: "{{ Access }}"
        DataSourceId: "{{ DataSourceId }}"
  - name: HierarchicalAccessControlList
    description: |
      The list of principal lists that define the hierarchy for which documents users should have access to.
    value:
      - PrincipalList: "{{ PrincipalList }}"
  - name: ClientToken
    value: "{{ ClientToken }}"
    description: |
      A token that you provide to identify the request to create an access control configuration. Multiple calls to the CreateAccessControlConfiguration API with the same client token will create only one access control configuration.

UPDATE examples

update_access_control_configuration

Updates an access control configuration for your documents in an index. This includes user and group access information for your documents. This is useful for user context filtering, where search results are filtered based on the user or their group access to documents. You can update an access control configuration you created without indexing all of your documents again. For example, your index contains top-secret company documents that only certain employees or users should access. You created an 'allow' access control configuration for one user who recently joined the 'top-secret' team, switching from a team with 'deny' access to top-secret documents. However, the user suddenly returns to their previous team and should no longer have access to top secret documents. You can update the access control configuration to re-configure access control for your documents as circumstances change. You call the BatchPutDocument API to apply the updated access control configuration, with the AccessControlConfigurationId included in the Document object. If you use an S3 bucket as a data source, you synchronize your data source to apply the AccessControlConfigurationId in the .metadata.json file. Amazon Kendra currently only supports access control configuration for S3 data sources and documents indexed using the BatchPutDocument API. You can't configure access control using CreateAccessControlConfiguration for an Amazon Kendra Gen AI Enterprise Edition index. Amazon Kendra will return a ValidationException error for a Gen_AI_ENTERPRISE_EDITION index.

UPDATE aws.kendra.access_control_configurations
SET 
IndexId = '{{ IndexId }}',
Id = '{{ Id }}',
Name = '{{ Name }}',
Description = '{{ Description }}',
AccessControlList = '{{ AccessControlList }}',
HierarchicalAccessControlList = '{{ HierarchicalAccessControlList }}'
WHERE 
region = '{{ region }}' --required
AND IndexId = '{{ IndexId }}' --required;

DELETE examples

delete_access_control_configuration

Deletes an access control configuration that you created for your documents in an index. This includes user and group access information for your documents. This is useful for user context filtering, where search results are filtered based on the user or their group access to documents.

DELETE FROM aws.kendra.access_control_configurations
WHERE region = '{{ region }}' --required
;

Lifecycle Methods

list_access_control_configurations

Lists one or more access control configurations for an index. This includes user and group access information for your documents. This is useful for user context filtering, where search results are filtered based on the user or their group access to documents.

EXEC aws.kendra.access_control_configurations.list_access_control_configurations 
@region='{{ region }}' --required 
@@json=
'{
"IndexId": "{{ IndexId }}", 
"NextToken": "{{ NextToken }}", 
"MaxResults": {{ MaxResults }}
}'
;