Search policies

This section aims to describe the concept of Search policies and their implementation/use for the purpose of multi-tenancy and/or document visibility separation in Search! based on users and roles when authenticating (via SSO) with the TK Portal application.

Search policies can be used for more complicated use cases than only segregating data between different users, such as enabling project sharing in Search! among various user groups, or giving the possibility to users that belong in different departments of the same company to switch between those departments and see the relevant documents when they do.

These complicated use cases will not be covered here since they require further analysis and they are subject to a customer’s internal requirements. They can always be discussed with a Textkernel Technical consultant when necessary.

Nevertheless, this document should always be used as foundation when working with Search policies for data segregation.

Concepts

Access roles

Each document in Search! is indexed with a tag called an access role (also known as a Search role). This tag is a field containing one or more values.

Upon logging in, users are also assigned one or more access roles. If a document is indexed with an access role that is also present in the list of user's active access roles, the user is allowed to see and perform operations on this document.

The access role structure supports a multi-dimensional role hierarchy, allowing for complex access roles schemes. Please refer to the Search! documentation's chapter Example Access Roles Scheme for more information.

Example use cases include segregating documents based on:

• Tenants (in a multi-tenant environment)
• Departments/business or units/offices
• Specific users
• User types, such as "recruiter" versus "manager"

In order to properly implement document visibility based on these access roles, it is important to (1) index a document with the respective access roles, and (2) grant the respective access roles to the user. This document describes (2).

Note

Only one matching access role is enough to have access to a document, i.e. when both the user and the document have at least one access role in common.

Search policies

A Search policy is a data structure that represents a group of settings in TKPortal. These settings include access roles, and other relational information. Search policies are expressed in JSON format.

A Search policy can have one or more Search! access roles assigned to it.

In turn, Users can be assigned to Search policies, thus granting them the access roles associated to the Search policy and enabling them to see in Search! only the documents they should have access to.

In summary, Search policies make it possible to dynamically add/remove access roles to a group of users.

Use cases for using Search policies

In previous sections, the technical aspects of Search policies have been covered. In this section, various use cases are described. The aim is to give an idea of the Search policies that shall be used for the most common access role schemes of an integration that contains multiple tenants.

One Search policy per tenant

Each user is able to access all the candidate/jobs documents of the tenant they belong to, and share projects only with users of the same tenant. This is described below:

This is the most common use case and can be resolved with one Search policy per tenant (which will hold the respective access role(s) of the tenant). Therefore, for these three tenants three policies need to be created:

[
    {
        "name":"policy1",
        "searchRoles":[
            {
                "name":"tenant1",
                "searchRef":"candidateSearch"
            },
            {
                "name":"tenant1",
                "searchRef":"jobSearch"
            }
        ],
        "sharesWith":[
            "policy1"
        ]
    }
]

[
    {
        "name":"policy2",
        "searchRoles":[
            {
                "name":"tenant2",
                "searchRef":"candidateSearch"
            },
            {
                "name":"tenant2",
                "searchRef":"jobSearch"
            }
        ],
        "sharesWith":[
            "policy2"
        ]
    }
]

[
    {
        "name":"policy3",
        "searchRoles":[
            {
                "name":"tenant3",
                "searchRef":"candidateSearch"
            },
            {
                "name":"tenant3",
                "searchRef":"jobSearch"
            }
        ],
        "sharesWith":[
            "policy3"
        ]
    }
]

When users access TK Portal, the Search policies that should be assigned to them are as follows:

• All users of Tenant 1 should be assigned to "policy1"
• All users of Tenant 2 should be assigned to "policy2"
• All users of Tenant 3 should be assigned to "policy3"

When Tenant 4 gets onboarded, the integrating application should create "policy4" in a similar way and should assign it only to users of Tenant 4.

Multiple Search Policies per tenant

Each tenant has a specific group of users - e.g. "recruiters" - that can see some of the candidate/job documents and another group of users - e.g. "managers" - that can see a different set of candidate/jobs documents.
Each user group can share projects with other users of the same group. This is shown below:

This is a more advanced case that can be resolved with two Search policies per tenant (there will be two access roles per tenant as well). Therefore, for these three tenants six policies need to be created in total. The two search policies of Tenant 1 are the following:

[
    {
        "name":"Tenant1RecruiterPolicy",
        "searchRoles":[
            {
                "name":"Tenant1RecruiterDocument",
                "searchRef":"candidateSearch"
            },
            {
                "name":"Tenant1RecruiterDocument",
                "searchRef":"jobSearch"
            }
        ],
        "sharesWith":[
            "Tenant1RecruiterPolicy"
        ]
    }
]

[
    {
        "name":"Tenant1ManagerPolicy",
        "searchRoles":[
            {
                "name":"Tenant1ManagerDocument",
                "searchRef":"candidateSearch"
            },
            {
                "name":"Tenant1ManagerDocument",
                "searchRef":"jobSearch"
            }
        ],
        "sharesWith":[
            "Tenant1ManagerPolicy"
        ]
    }
]

The Search policies for the rest of the tenants can be created in a similar way by adjusting the policy name and the access roles names accordingly.

When users SSO, the policies that should be assigned to them are as follows:

• All "recruiter" users of Tenant 1 should be assigned to Tenant1RecruiterPolicy
• All "manager" users of Tenant 1 should be assigned to Tenant1ManagerPolicy
• The same pattern should be followed for the rest of the tenants.

If Tenant 1 wants to enable a user to access both types of documents, then the integrating application would simply have to assign both aforementioned policies to this user.