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
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:
-
[If
isUserReferencedByEmail
is set to false]
Index usersuser1@test.com
anduser2@test.com
before moving to further steps (To learn how to index users, please refer to Scenario 1B or Scenario 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”
-
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 ifisUserReferencedByEmail
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 thememberUserId
field (Exactly one of the two fields must be present).
-
-
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.