Permissions

The content in Glean is highly customizable in terms of configuring visibility of documents, which can be noted while indexing documents using Indexing API endpoints. Glean may require some more information to manage users, groups and group memberships to enable the full power of customized permissions. This can be done using Permissions API endpoints.

This tutorial assumes that you have followed the documentation / other tutorials to set up a custom datasource and know how to use the Indexing API to index documents. If not, check out the documentation and other tutorials available.

We shall consider various scenarios with increasing complexity of permissions used, along with some example requests which can be used to reproduce them.

Scenario 0: Allowing any glean user to search for a document

The most basic way to configure permissions for a document is to allow any Glean user within the organization to be able to search for a document. This can be accomplished by setting the allowAnonymousAccess field to be true while setting up permissions for a document.

For example, the following request to index a document would lead to the document being visible to all Glean users:

curl -X POST https://customer-be.glean.com/api/index/v1/indexdocument \
#... 
   "permissions": {
	"allowAnonymousAccess" = "true"
   }
#... Rest of the document

Scenario 1: Explicitly allowing users that can search for a new document

Let’s address a simple scenario: We have a document and want to explicitly allow some users to be able to search for it using Glean.

Based on the configuration provided while setting up the datasource, we can have two different sets of steps to be followed to achieve our use-case.

Scenario 1A: isUserReferencedByEmail field set to true in the datasource config

In case isUserReferencedByEmail is set to true, there is no need to call any Indexing API endpoint to index users to achieve our use-case. We can create a document with its allowedUsers field to capture users that can search for it. Assumption: The users are already a part of people data for the Glean customer.

The following sample creates a document, only allowing user1@test.com (already part of people data for the Glean customer) to search for it using Glean.

curl -X POST https://customer-be.glean.com/api/index/v1/indexdocument \
# ...
   "permissions": {
 	  "allowedUsers": [
    	  {
        	  "email": "user1@test.com",
              "name": "Test User 1"
        }
      ]
   }
# ... Rest of the document

Scenario 1B: isUserReferencedByEmail field set to false in the datasource config

In case isUserReferencedByEmail is set to false, users need to be indexed before being referenced elsewhere (for example: while defining permissions). This is mainly because the config being set to false implies that a user would be referred by a defined user ID besides their email address. Let us look at the following sample request to understand better:

curl -X POST https://customer-be.glean.com/api/index/v1/indexuser \
  -H 'Authorization: Bearer <Token>' \
  -d '
{	
  "datasource": "gleantest",
  "user": {
    "email": "user1@test.com",
    "userId": "gleantest_user_1"
    "name": "Test User 1",
    "isActive": "true"
  }
}'

The above request indexes user user1@test.com with userId gleantest_user_1.

We can create a document with its allowedUsers field to capture previously indexed users. The following sample request creates a document, only allowing gleantest_user_1 to search for it using Glean.

curl -X POST https://customer-be.glean.com/api/index/v1/indexdocument \
# ...
   "permissions": {
 	  "allowedUsers": [
    	  {
        	  "datasourceUserId": "gleantest_user_1",
              "name": "Test User 1"
        }
      ]
   }
# ... Rest of the document

Scenario 2: Allowing all users of the datasource to search a document

We shall move to a different scenario: We now want to allow all users of the datasource to be able to access a particular document. To achieve this, we must define “users of the datasource” by indexing all relevant users.

For example, if we only want user1@test.com to be a “datasource user”. We use the following sample request to index the user.

curl -X POST https://customer-be.glean.com/api/index/v1/indexuser \
  -H 'Authorization: Bearer <Token>' \
  -d '
{	
  "datasource": "gleantest",
  "user": {
    "email": "user1@test.com",
    "name": "Test User 1",
    "isActive": "true"
  }
}'

We can create a document with its allowAllDatasourceUsersAccess field set to true to allow all datasource users. The following sample request creates a document that is accessible to all datasource users (i.e. only user1@test.com in this case) using Glean.

curl -X POST https://customer-be.glean.com/api/index/v1/indexdocument \
# ...
   "permissions": {
	"allowAllDatasourceUsersAccess" = "true"
   }
# ... Rest of the document

Scenario 3: Allowing pre-defined groups of users to search for a document

For this scenario, we want to pre-define specific groups of users which are all to be given access to a document. For instance, a specific team within the organization may have access to a chunk of documents within the datasource. This can be achieved by indexing a group with all members of that team and allowing this group to access each relevant document. We shall learn more about this using an example.

Let us assume that we have two users user1@test.com and user2@test.com and the datasource is configured to have the isUserReferencedByEmail field set to true (Note: In the other case where this bit is false, these users need to be indexed before moving forward, please refer to Scenario 1B to see how users can be indexed). We shall index a group gleantest_group_1 with the two users as their members, and then create a document that allows gleantest_group_1 to access it. This should implicitly allow user1@test.com and user2@test.com to search for the document using Glean.

The following sequence of steps (with sample API calls) should help us reproduce the above mentioned situation:

1. [If isUserReferencedByEmail is set to false]
   Index users user1@test.com and user2@test.com before moving to further steps (To learn how to index users, please refer to Scenario 1B or Scenario 2 ).

2. Index a group named gleantest_group_1 using the /indexgroup endpoint:

 curl -X POST https://customer-be.glean.com/api/index/v1/indexgroup \
  -H 'Authorization: Bearer <Token>' \
  -d '
  {
  	"datasource": "gleantest",
    "group": {
    	"name":"gleantest_group_1"
    }
  }'

Some key points about fields in the request body:

• name : It is the identifying key for a group within a datasource. There are a few considerations while defining the name of the group:
  • Cannot contain any whitespaces
  • Cannot be empty
  • Cannot start with the prefix “scio”

3. Index memberships for each of the two test users using the /indexmembership endpoint:

# Index membership for user1@test.com
curl -X POST https://customer-be.glean.com/api/index/v1/indexmembership \
  -H 'Authorization: Bearer <Token>' \
  -d '
  {
    "datasource": "gleantest",
    "membership": {
      "groupName": "gleantest_group_1",
      "memberUserId": "user1@test.com"
    }
  }'

# Index membership for user2@test.com
curl -X POST https://customer-be.glean.com/api/index/v1/indexmembership \
  -H 'Authorization: Bearer <Token>' \
  -d '
  {
    "datasource": "gleantest",
    "membership": {
      "groupName": "gleantest_group_1",
      "memberUserId": "user2@test.com"
    }
  }'

• Some key points about fields in the request body:
  • groupName : A group with this particular groupName must be indexed before indexing memberships for it.
  • memberUserId : This identifies a particular user as a member of the group. This must be the email ID of the user if isUserReferencedByEmail is set to true. In the other case, this field must be the userId specified while indexing the user.
  • Note : In case a group needs to be added as a member of another group, that can be done by using the memberGroupName field in place of the memberUserId field (Exactly one of the two fields must be present).

4. Create a document with the allowedGroups field to include gleantest_group_1 . This would allow members of the group to search for the document using Glean.

curl -X POST https://customer-be.glean.com/api/index/v1/indexdocument \
# ...
   "permissions": {
 	  "allowedGroups": ["gleantest_group_1"]
   }
# ... Rest of the document 

Notes and next steps

• Note: Permissions and memberships are processed asynchronously, there might be a small delay before documents are visible to groups / users in Glean searches.
• This tutorial only covers singleton variants of endpoints that have a bulk upload version. The bulk upload endpoints are similar to their singleton variants, following the bulk upload model and can be used when bulk indexing is required.
• You can check permissions by using the /checkdocumentaccess API endpoint. Check out the debugging/troubleshooting tutorial for examples and additional helpful information.