RACL Overview

Introduction

RACL stands for Role-Based Access Control List, which refers to the method of controlling access to specific resources or information based on the roles of individual users within the organization. Through RACL, the enterprise search application can ensure that users only see search results and answers and access documents or information relevant to their roles within the organization. This helps maintain data security, confidentiality, and compliance with organizational policies and regulations.

In the context of SearchAssist, this feature allows users to access search results and answers only from the content they can access. In other words, SearchAssist displays content based on the end user’s identity.

Each file or knowledge base article has associated user access permissions. During data ingestion, this information is fetched from the third-party application and stored as metadata in the indexed content, along with content and other details about the content. When a user submits a query to SearchAssist, the application identifies all pertinent content that the user can access and then presents the results to the users.

Access control in SearchAssist can be summarized with the following flowchart.

The response to a query can vary depending on the end user’s identity. Consider two users, where one can access the company’s policy documents and the other can only access the FAQs. If a policy description is requested, the first user will see the response generated from the policy document (assuming the best match to the query). On the other hand, since the second user cannot access the policy document, he will see the response generated from the FAQs (assuming the next best match). The response will differ in this case depending on the content of the two documents.

Note: This feature is currently in beta. If you encounter any issues, please contact our support team. We will help you resolve the issue.

Implementation in SearchAssist

During the ingestion process, SearchAssist imports the permissions (list of users, user groups, or user criteria- depending on the specific connector) that define who can access a particular file or article, along with the content and metadata. This access information is stored within the indexed content. Specifically:

In the Search Index, the access information is stored in the sys_racl field.
In the Answer Index, it is stored in the sourceAcl field.

When a user submits a query to the application, results are displayed only if the user’s identity is listed in the sourceAcl or sys_racl field of the content from which the results are derived.

Example: Consider a Google Drive file owned by John and shared with Smitha and Abby. In this case, the sourceAcl field will contain the identities of all three users. As a result, any answers generated from this file will be accessible only to John, Smitha, and Abby.

Due to variations in the nature of permissions and scopes across different connectors, distinct sets of permissions are used to create the Permission Entities and populate the sourceAcl or sys_racl fields for content from different connectors. For more details, please refer to the documentation specific to each connector.

Implementation Steps

Retrieving and Storing Access Information

When RACL is enabled, the connector fetches document permissions along with its content from the source using the APIs provided by the source or the third-party application (e.g., Google Drive). The type of permissions depends on the supported mechanism in the backend application. For specific details, refer to the documentation of the respective connector.

The permissions retrieved from the document are stored in the sys_racl field in the Search Index and the sourceACL field in the Answer Index.

The permissions for an item can be broadly categorized into the following types:

Individual permissions– where the content (file, knowledge article, etc.) specifies the list of user identities that can access it ( for example, user1@example.com, user2@example.com, etc.).In this case, user identities are retrieved and stored in the racl field of the indexed content as shown below.
```
"sourceAcl": [
 "abraham.lincoln@example.com",
 "bernard.laboy@example.com"
 ],
```
Group Permissions: where the content specifies a group of users or a criteria that defines who can access it (for example, search-devteam@example.com).When the access information retrieved from the content refers to group permissions, SearchAssist uses Permission Entities. A unique permission entity is created for each group or user criteria associated with the content. For example, if a Google Drive file is accessible to two individuals, “john.divi@kore.com”, “smitha.joseph@kore.com” and to all the members of the group “searchassisttest@gmail.com”, SearchAssist will fetch the access list and store it in the indexed content. In this case, the first two entries are corresponding to the users and the third is corresponding to the permission entity created for the group. Similarly, if a ServiceNow article gives access to two user criteria, SearchAssist will create two Permission entities corresponding to the user criteria. The article’s manager and owners will also be granted access. Hence, the sourceACL field will be something like this: the first two entries are for the permission entities, and the next two are for the article’s owners and managers.
```
"sourceAcl": [
 "25431493ff4221009b20ffffffffffe0",
 "29b4e0c9873023000e3dd61e36cb0b42",
 "abraham.lincoln@example.com",
 "bernard.laboy@example.com"
 ],
```
Note that the content and format of the permission entity can vary between connectors.
Public Access: Where the content has no specific permissions associated with it and is accessible to all. In this case, no access control is required. The racl fields in the indexed content are set to *, as shown below. Any file indexed in this way will be accessible to all the users of SearchAssist.

View Permission Information

To view and verify the user permissions in the Answer Index, go to the Chunk Browser, open the JSON view of a chunk corresponding to the file, and verify the contents of the sourceACL field.

Similarly, the Workbench Simulator can be used to verify the sys_racl field values for data in the Search Index.

Verifying user identities

When a user sends a query, SearchAssist uses the user identity information and displays results or answers only if the user has permission to access the specific resource from which the results are generated.

The user identity is matched against the Permission entities corresponding to the content. In case, the user belongs to a group and the group is a permission entity for the content, SearchAssist needs additional information about the association of the user and the permission entity. Refer to the Handling Group Identities section below.

Passing User Identities in Search APIs

When the user interacts with SearchAssist via APIs( fullsearch, livesearch and advancedSearch), the user must send the identity information along with other fields in the request object. The user cannot access restricted content unless the identity information is passed.

SearchAssist allows passing user identity through both the request header as well as the request body. The system admin configures this. Contact your system admin to learn about the variable name and format for passing the user identity information in the search APIs.

For instance, if the user identity information is mapped to a field named ‘useremail’ sent as part of Request Headers, invoke the fullsearch or advancedSearch API accordingly.

curl --location --request POST 'https://searchassist-qa.kore.ai/searchassistapi/external/stream/st-670f1a12-9xxxxxx5c3f/fullsearch?useremail=myemail@example.com' \
--header 'Content-Type: application/json' \
--header 'integration-service: general' \
--header 'service-host: https://solutions-pilot.kore.ai/api/1.1/public/tables/' \
--header 'datatable: pushnotificationstable-dev' \
--header 'Auth: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBJZCI6ImNzLTZkMDUzMWZjLTIwODYtNTk1My1iZGNmLTEyNGFmNDJiMDhhOSJ9.sqytj0H8fKl_sj39Q87UaqjoqT-TFW0Z9GbULGdQaPQ' \
--data-raw '{
  "query":"AI regulations"
}'

Passing User Identities from SDK

When using an SDK to perform a search using the SearchAssist application, you can embed the user identity information into the SDK code so that SearchAssist can identify the user and perform access checks as needed.

To enable SDK to interact with the SearchAssist application, you must change the findly.config.ts file under src/components/search/config in the SDK code. Along with the information passed in the SearchConfig object, pass the user identity information as shown below.

KoreSearchSDK.KRSearchConfig.botOptions.userIdentity = 'PLEASE_ENTER_USER_EMAIL_ID';

For more information on config changes in the SDK, refer to this.

Resolving user identity

When a user group or user criteria is used to define a file’s access list, the indexed content contains a Permission Entity corresponding to the user group. In this case, SearchAssist needs additional information to resolve user identities. For example, if a file is accessible only to employees in the HR department, the permission entity generated for the file will reflect departmental access and will not have information about the individual users associated with the group.

In such a case, SearchAssist needs additional information to determine the association between the users and the groups. This can be done with the help of Permission Entity APIs, which can be used to add or remove users from a group. Learn more about Permission Entity APIs here.

Set up

RACL is currently supported for content ingested from connectors. To enable RACL, go to the Permissions and Security tab under the corresponding connector configuration and select the Default Access option as shown below.

This enables SearchAssist to read the default permissions associated with the content for different users in the third-party application.

When RACL is enabled i.e., the access is changed from Public Access to Default access, manually initiate the synchronization of content from the corresponding connector. This allows the connector to fetch access information for the ingested content. If a sync with the connector is scheduled in the future, updated permissions will apply after the next sync activity.

When the access is changed from Default Access to Public Access, the connector automatically disables the RACL feature and makes the content publicly available. Sync operation is not required in this case.

On this Page