Content Access Control via API

Many of our customers use complex content access control on their source systems. For example, User Criteria on ServiceNow or Group based access control on Confluence content. These types of access control configurations are very complex, many times involves custom scripts that evaluates access. It's not possible to apply such access control outside the context of the source system.

To support such configurations, the Aisera Gen AI platform has support for API-based access control. It is configured on a Data Source.

For ServiceNow, you can use this configuration for applying access control on both Knowledge Articles and Service Catalog Items.

Make sure the user ingestion is setup on a schedule. To check whether a user has access to content, the platform uses the user’s id from the SOR. User ingestion makes sure the platform can access a user’s external ID.

Tenant configuration

You also need to enable the tenant level flag Access Management from Settings > Configuration apart from Data Source level setup.

Tenant Configuration Parameters

Data Source Configuration

External API Access

Parameter
Definition

External API Access Management

Flag to enable access control via an API.

This configuration will be used for all articles ingested via this DS.

API to Check Access

Relative path of the API. External system endpoint will be prefixed with this relative URL to build final url.

SerivceNow: This SOR does not have any out of box API to check User Criteria based access control. So we have build a scripted api that customer need to install on their system. More details here. Once customer installs the package(update set) then the API value will be /api/aiser/user_criteria_check/check. THIS IS A FIXED VALUE FOR ALL ServiceNow.

Confluence: The api is provided by confluence/jira. The API value will be rest/api/content/{}/permission/check THIS IS A FIXED VALUE FOR ALL Confluence.

Attribute Based Contextual Filter

In addition to checking if user can view the content or not, we can apply additional filter on it via this filter. The configured filter at DS level will be applied to KBs ingested via this the KB only.

You can build the option filter using the following steps.

The optional filter is applied with Access Attributes that are active and marked not required. For example, you want to apply a filter based on language. If user asks a question in German and multiple documents are available on the topic with different languages, then you want the bot to provide an answer from the Knowledge Base that is written in German. But what if there is no Knowledge Base Article in German for the topic but there is Knowledge Base Article in English? In this case, the bot can use the English document as a fallback document to answer the user’s question.

The Aisera Gen AI platform uses JEXL based expressions to define such filters. For access attribute based filters you can define it at the tenant level. Settings > Configuration > Access Management > Access policy for optional attributes .

Single value attribute

The expression for the examples above will be similar to this: (entity.language == null || entity.language == '' || entity.language == 'en' || entity.language == user.language)

With these expressions, you define the following:

  1. If a Knowlege Base Article does not have the attribute language then user can view it (entity.language == null)

  2. If a Knowledge Base Article has an empty value for thelanguageattribute, then the user can view it (entity.language == '')

  3. If a Knowledge Base Article has a value and it is en(English) for the language attribute, then the user can view it (entity.language == 'en')

  4. If a Knowledge Base Article has a value other than en then it should match the user’s language to allow the user to view the article. (entity.language == user.language)

ServiceNow Update Set

Ask your Aisera Team to retrieve an Update Set for your specific data source.

Validating SerivceNow API

After the customer has installed this update set, you can validate whether the API is working as expected on ServiceNow.

  1. Navigate to REST API Explorer on ServiceNow.

  2. Select aiser from Namespace .

  3. Select User criteria check from API Name .

  4. Use the following sample payload. Replace userId with the sys_id of the some user on their system. Also update IDs under knowledgeDocuments with some of the Knowledge Base Article numbers from their system. If you want to test the Service Catalog then replace ids under catalogItems with sys_ids of some Service Catalog items. Try the api with few sample users.

    { "userId": "a0f7e879db219150996f4a7f0596193f", "knowledgeDocuments": [{ "id": "KB1233" }, { "id": "KB4455" }], "catalogItems": [{ "id": "9e274809db6ddd10996f4a7f059619fa" }] }

  5. The output of the API will look something like this. ThecanView field diplays whether the user has access to KBAs/Service Catalog Items.

    { "userId": "a0f7e879db219150996f4a7f0596193f", "knowledgeDocuments": [{ "id": "KB1233", "canView” : true }, { "id": "KB4455", "canView": false }], "catalogItems": [{ "id": "9e274809db6ddd10996f4a7f059619fa", "canView": true }] }

User criteria with script

Many customers use a script in their User Criteria. If they are not using appropriate system variable user_id for user’s id in the script then the user criteria will not work properly when checked via an API. Please suggest customer to use pre-defined variable user_id.

Refer to this ServiceNow documentation.

Last updated