Role Based Filtering

In order to implement role-based filtering of search results, you need to use the principal_sets feature.

You must have an index where you have write permissions, and you must know the Group IDs or Identity IDs of the users and groups for whom you want to assign roles in your data.

API Methods

We will leverage these API methods:

Ingest API	Submit an Ingest Task
Get Query	Perform a simple query

You must have a means to use these APIs. For example, the Globus CLI.

Step 1: Identify Roles for Data

For the purposes of example, we will assume that we have two users, with IDs I and J, and groups with IDs G and H.

Furthermore, we’ll define roles on a few documents as follows:

Table 1. Document-to-Roles
`doc0`	No roles
`doc1`	`I` and `J` are `admin`, `G` is `monitor`
`doc2`	`H` is `monitor`

Let us assume, for simplicity, that doc0, doc1, and doc2 are all public data.

Note

Roles and visible_to are orthogonal and can both apply correctly to the same search.

In order to appear in search results, you must match both criteria if they are used.

Step 2: Define a GIngest document which encodes these roles

Using principal_sets, we would notate this by putting I, J, G, and H into Principal URNs and assigning them to each document.

Wrapping this in a GIngest document, we would see something like so:

Example 1. GIngest with principal_sets

{
  "ingest_type": "GMetaList",
  "ingest_data": {
    "gmeta": [
      {
        "subject": "doc0",
        "visible_to": [
          "public"
        ],
        "content": {
          "foo": "value0"
        }
      },
      {
        "subject": "doc1",
        "visible_to": [
          "public"
        ],
        "principal_sets": {
          "admin": [
            "urn:globus::auth:identity:I",
            "urn:globus::auth:identity:J"
          ],
          "monitor": [
            "urn:globus:groups:id:G"
          ]
        },
        "content": {
          "foo": "value1"
        }
      },
      {
        "subject": "doc2",
        "visible_to": [
          "public"
        ],
        "principal_sets": {
          "monitor": [
            "urn:globus:groups:id:H"
          ]
        },
        "content": {
          "foo": "value2"
        }
      }
    ]
  }
}

We don’t care much about the content for this example, so each contains only one field, foo.

Step 3: Query the data

In order to query this data, use the filter_principal_sets parameter.

For example, I and J would find only doc1 if they query in the form

GET /v1/index/<index_id>/search?q=*&filter_principal_sets=admin

If I is a member of group H, they would find doc1 and doc2 with the query

GET /v1/index/<index_id>/search?q=*&filter_principal_sets=admin,monitor

For any user, the following query is valid but returns no results:

GET /v1/index/<index_id>/search?q=*&filter_principal_sets=nosuchrole