Content Access Control via APIs

Implement access control to your content using APIs

Many systems employ complex content access control, such as User Criteria on ServiceNow or group-based access control on Confluence. These configurations can be intricate, often involving custom scripts for access evaluation. Such access control cannot be replicated outside the context of the source system.

To support such configurations, the Aisera platform has support for API-based access control. It is configured within a Data Source, and allows you to use the external system's built in APIs to apply access controls to the content ingested into the Aisera Platform.

For systems like 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.

Supported Use Cases for Access Control via API

In the following use cases, note that the applications/bot can recognize regions in user requests, such as APAC, EMEA, or EU.

Category	Supported Use Cases
ServiceNow - Aisera API	This is limited to Aisera's Update Set in ServiceNow
ServiceNow - Aisera Attributes	Region based responses, for example, regional Holidays. Group based responses using a tag-based solution, such as HR group.
Confluence Cloud - Aisera API	This is limited to the reference implementation listed in Atlassian API Documentation. This only supports the Check Content Permissions API. This only supports users with permissions to see "anyone" email. The prerequisites for this include the following: Users are ingested with user emails. Ingested users have a Confluence Account ID as an external ID. The Data Source with the User Learning function is defined as a System of Record (SOR). The email of the ingested user records should be the same email used for the data sources.
Confluence Cloud - Aisera Attributes	Region based responses, for example, regional Holidays. Prerequisites for this use case include: The region or language attributes should be a custom field in the ingested articles The region or language should be ingested in the User Profiles
Confluence On-Premises Installation - Aisera API	This is not supported. On-premises installations of Confluence do not have permissions to check APIs.
Confluence On-Premises Installation - Aisera Attributes	Region based responses, for example, regional Holidays. Prerequisites for this use case include: The region or language attributes should be a custom field in the ingested articles The region or language should be ingested in the User Profiles

Tenant Configuration

You will need to enable the Enable Access Management feature. Once enabled, Access Management will be enabled tenant wide, allowing for access control to be enabled on any data source.

This configuration is found under Settings > Configuration > Access Management.

Tenant Configuration Parameters

Data Source Configuration

After enabling access management, you will need to configure your data source for access management.

Navigate to Settings > Data Sources and choose the Data Source for which you want to enable access management. On the Data Source Details screen, click the Pencil icon in the upper right to edit, then select Configuration. Set External API Access Management to Yes.

When you choose the Yes option for External API Access Management, you will see two additional fields, API to check access and Attribute based contextual filter. The ServiceNow example below, displays this screen with values in these fields.

External API Access

Parameter	Definition
External API Access Management	This flag enables access control via an API for all articles ingested through this data source.
API to Check Access	This is the relative path of the API used to check if a user has access to content ingested by this data source. The external system endpoint will be prefixed with this relative URL to build the final URL. Check the sections below for more information about your specific use case.
Attribute Based Contextual Filter	In addition to checking if the user can view the content or not, you can apply an additional filter to it. The configured filter at the data source level will be applied to KB Articles ingested via this KB only.

ServiceNow API

The ServiceNow data source does not have an out-of-the-box API to check user criteria based access controls. Instead, a scripted API will need to be installed on your system. Contact your Aisera team for the install package.

Once the package has been installed, the relative API path will be: /api/aisera/user_criteria_check/check

Validating the ServiceNow API

After installing the update set provided to you by your Aisera team, you will need to validate the API is working as expected. To validate the API is working:

1. Navigate to Rest API Explorer within ServiceNow.

2. Select aisera from Namespace.

3. Select User criteria check from API Name.

4. Use the following sample payload.

   1. Replace userId with the the sys_id of a user on your system.

   2. Update the IDs under knowledgeDocuments with the IDs of knowledge articles within your system.

   3. If you want to test the Service Catalog, replace the IDs under catalogItems with the sys_ids of some Service Catalog items.

   4. Try these inputs with multiple users.

      {
          "userId": "0123456789abcdef0123456789abcdef",
          "knowledgeDocuments": [{
              "id": "KB1234"
          }, {
              "id": "KB1235"
          }],
          "catalogItems": [{
              "id": "0123456789abcdef0123456789abcdef"
          }]
      }

5. The output of the API should look similar to the the following example output. The canView field displays whether user has access to the specified content:

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

User Criteria with Scripts

You may be using a script in your User Criteria. If you are not using the predefined user_id for your user's ID in the script, the user criteria will not work properly when checked by an API. It is recommended that you use the pre-defined user_id.

Refer to this ServiceNow documentation.

Confluence API

This API is provided by Atlassian. the API value will be: rest/api/content/{}/permission/check

Optional Filters

Optional filters are filters applied using Access Attributes specified on the Aisera Platform. Filters may include attributes like language, location, department, and others. These filters are applied by using Access attributes that are marked as Enabled, but not Required. These are considered "Soft Filters" because they allow for a fallback response when a document meeting the exact filter requirements cannot be found.

For example, you may want a bot to prioritize documents in the user's native language. If a user asks a question in German, the bot will first search for a German version of the answer. However, if no German article exists, the optional status of the access attribute allows the bot to ignore the language constraint and fallback to providing an English document instead. This ensures the user gets an answer even if a match is not available.

The Aisera platform uses Java Expression Language (JEXL) based expressions to define such filters. You can define Access Attribute based filters at the tenant level. To do so, navigate to Settings > Configuration > Access Management > Access Policy For Optional Attributes.

Note that you can also set Access Attributes at the application/bot (not Tenant) level.

Sample Implementation

The following expression is an example of a filter:

(entity.language == null || 
 entity.language == '' || 
 entity.language == 'en' || 
 entity.language == user.language)

With these expressions, you define the following:

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

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

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

4. entity.language == user.language: 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.