Search With Permissions

Once you centralize fine-grained authorization to protect your resources, search becomes a more complex problem, because the user's access now has to be validated for each resource before that resource can be shown.

The search problem can then be summarized as:

"Given a particular search filter and a sort order, what objects can the user access"?

The Auth0 FGA service does not store object metadata (names of files, creation dates, time of last update, etc), adding filtering and sorting on top of any search query will require data from your database.

The services responsible for performing these actions are:

• Access: Auth0 FGA
• Filter: Your database
• Sort: Your database

To return the proper set of results that match the user's search query, you will need to get the intersection of the results from these two separate data sources: your business data that lives in your application database and authorization data that lives in FGA.

Possible options

There are four possible ways to do this:

Option 1: Search, then check

Pre-filter, then call the Batch Check API.

1. Filter and sort on your database.
2. Call /batch-check to check access for multiple objects in a single request.
3. Filter out objects the user does not have access to.
4. Return the filtered result to the user.

There is no guarantee that the user will have access to any of the results returned by the database query. Consider the possibility of making multiple Batch Check request to eventually fill a paginated list of results.

Option 2: Fetch a list of authorized IDs, then search

Call the List Objects API to get a list of object IDs the user has access to, then run the filter restricting by the object IDs returned.

1. Call /list-objects to get the list of all resources a user can access.
2. Pass in the set of object IDs to the database query to limit the search.
3. Return the filtered result to the user.

Be aware that the performance characteristics of a List Objects request vary drastically depending on your authorization model complexity and tuple distribution (i.e. cardinality) across your model. Relations with and or but not are more expensive to evaluate than relations with or.

Option 3: Use FGA Permissions Index

Auth0 FGA offers a Permissions Index to continually maintain a fully "flattened" set of permissions. The Permissions index pre-calculates all permission combinations at write time and stores them as direct user-to-object relationships for constant lookup at query time.

1. Create a Permissions Index in Auth0 FGA.
2. Stream expansion changes into your local database, such as PostgreSQL, Snowflake, or ElasticSearch.
3. Join or filter between your business data and the colocated permissions index.

The Permissions Index assumes a calculated tradeoff: do the expensive work when permissions change, not when someone is checking for access. This makes it ideal for search workloads, where you want to return results as quickly as possible, but you can tolerate some delay between when a permission is granted or revoked and when that change is reflected in search results.

Option 4: Build a local index from changes endpoint, then search

Consume the Changes API to create a local index you can use to do an intersection on the two sets of results.

1. Call the /changes endpoint to get every tuple write or delete event.
2. For the particular authorization model version(s) you are using in production, flatten/expand the changes
   • (e.g. user:anne, writer, doc:planning becomes two tuples: user:anne, writer, doc:planning and user:anne, reader, doc:planning).
3. Build the intersection query between the objects in your database and the flattened/expanded index you created.

Choosing the best option

Which option to choose among the four listed above depends on the following criteria:

1. Number of objects that your database can return from a search query
2. Number of objects of a certain type the user could have access to
3. Percentage of objects in a type the user could have access to

Consider the following scenarios:

A. The number of objects a search query could return from the database is low.

Search then Check is the recommended solution.

Use-case: Situations where the search query can be optimized to return a small number of results.

B. The number of objects of a certain type the user could have access to is low, and the percentage of objects in a namespace a user could have access to is high.

Search then Check is recommended to get the final list of results.

Note that this use case, because the user has access to a low number of objects which are still a high percentage of the total objects in the system, that means that the total number of objects in the system is low.

C. The number of objects of a certain type the user could have access to is low (~ 1000), and the percentage of the total objects that the user can have access to is also low.

In this case, using the GET /list-objects would make sense. You can query this API to get a list of object IDs and then pass these IDs to your filter function to limit the search to them.

As this number increases, this solution becomes impractical, because you would need to paginate over multiple pages to get the entire list before being able to search and sort. A partial list from the API is not enough, because you won't be able to sort using it.

So while List of IDs then Search would be useful for this in some situations, we would recommend Use the Permissions Index or Local Index from Changes Endpoint, Search then Check for the cases when the number of objects is high enough.

D. The number of objects of a certain type the user could have access to is high, and the percentage of the total objects that the user can have access to is low.

The recommended option for this case is to use Use the Permissions Index or Local Index from Changes Endpoint, Search then Check.

• List of IDs then Search would not work because you would have to get and paginate across thousands or tens of thousands (or in some cases more) of results from Auth0 FGA, only after you have retrieved the entire set can you start searching within your database for matching results. This would mean that your user could be waiting for a long time before they can start seeing results.

• Search then Check would also not be ideal, as you will be retrieving and checking against a lot of items and discarding most of them.

Use case: Searching in Google Drive, where the list of documents and folders that a user has access to can be very high, but it still is a small percentage of the entire set of documents in Google Drive.

You can consider the following strategies to transform this scenario to a type B one:

• Duplicate logic from the authorization model when querying your database. For example, in a multi-tenant scenario, you can filter all resources based on the tenant the user is logged-in to. Duplicating logic from the authorization model is not ideal, but it can be a reasonable trade-off.

• Retrieve a higher-level resource ID list with lower cardinality for efficient filtering. For example, in a document management application, first obtain the list of accessible folders for the user. You can then filter documents by these folders in your database query. This approach increases the likelihood that the user can access the documents in those folders, optimizing the query’s effectiveness.

E. The number of objects of a certain type the user could have access to is high, and the percentage of the total objects that the user can have access to is also high.

In this case a Use the Permissions Index or Local Index from Changes Endpoint, Search then Check would be useful. If you do not want to maintain a local index and the user can access a high percentage of the total, meaning that the user is more likely than not to have access to the results returned by the search query, then Search then Check would work just as well.

Use-case: Searching on Twitter. Most Twitter users have their profiles set to public, so the user is more likely to have access to the tweets when performing a search. So searching first then running checks against the set of returned results would be appropriate.

Summary

Scenario	Use Case	# of objects returned from database query	# of objects user can access in a type	% of objects user can access in a type	Preferred Option
A	Search criteria enough to narrow down results	Low	-	-	1
B	Few objects the user has access to, but still a high % of total objects	Low	Low	High	1
C	Cannot narrow down search results, very high probability search returns objects user cannot access, total number of objects user can access is low enough to fit in a response	High	Low	Low	2, 3, or 4
D	Google Drive: User has access to a lot of documents, but low percentage from total	High	High	Low	3 or 4
E	Twitter Search: Most profiles are public, and the user can access them	High	High	High	1, 3, or 4