Launch Week, Day 2 - Warrant Query Language & Query API

Welcome to day 2 of our first Launch Week! On day 1, we introduced the new and improved v2 Warrant API. In case you missed it, you can catch up on the details here. Now let's get into day 2!

Warrant Query Language (WQL)

In a recent blog post, Why Google Zanzibar Shines at Building Authorization, we detailed why Google Zanzibar is extremely well-suited to handling application authorization. One of the key reasons we covered is that Zanzibar is a stateful, centralized authorization service. This means the authorization rules for an application (along with any other data necessary to make authorization decisions for the application) are stored centrally in Zanzibar, making it possible to query access rules for a user or resource in real time without the need to consult another data source. This allows developers to not only audit users' access rules but to also query Zanzibar directly from their application to fetch only the resources a user has access to.

Today, we're excited to introduce the Warrant Query Language (WQL), a declarative, SQL-like language for querying Warrant for lists of access controlled data from the context of an application. In particular, WQL is there to help developers answer two types of queries from within their applications:

1. Which objects of type T does user U have access to?
2. Which users have access to object O?

With the ability to answer these two types of queries, WQL makes it easy for developers to handle the listing of access controlled resources (e.g. your Google Drive home page, the list of nav elements to render for a user of an enterprise dashboard, etc.) without having to repeatedly call Warrant's check endpoint. Let's look at a couple of examples.

Paid Features in a SaaS Dashboard

Imagine we work on a team maintaining the admin dashboard of a SaaS application. This SaaS application offers a free tier with access to a limited number of free features and multiple paid tiers with increasing access to paid features (pro, enterprise, etc). The admin dashboard we maintain has a left nav which should only display the features available to the user based on their subscription tier (i.e. free tier users only see the free features and so on).

We can easily set up an authorization model matching this scenario using Warrant's built-in pricing-tiers support, but we still need to get the list of features the user has access to for constructing the left nav. We can fetch this list with the following WQL query:

Get all features user U has access to

select feature where user:U is member

Google Docs Sharing

Now, let's say we're building a competitor to Google Docs. We're tasked with building the document sharing functionality. We can easily build an authorization model matching this scenario with Warrant's built-in fine-grained access control (FGAC) support, but we need to be able to list the users who have access to a given document (for the Share modal). We can fetch the list of users with access to a given document with the following WQL query:

Get all users who have at least viewer access to document D

select viewer of type user for document:D

The Query API

To make it easy for developers to run WQL queries from their applications, we're also introducing the Query endpoint. The query endpoint accepts a query written in WQL and returns the list of results the query yields. All of our SDKs have already been updated with support for the query endpoint!

Each result from the query endpoint contains:

• The object matching the query, including any metadata associated with it.
• The top-level warrant that caused the object to be included in the query result (e.g. user has feature F because the user has pricing-tier P).
• A boolean flag indicating whether the result is implicit.

Here's what a complete response looks like:

GET /v2/query?q=select+feature+where+user:john+is+member

{
    "results": [
        {
            "objectType": "feature",
            "objectId": "invite_user",
            "warrant": {
                "objectType": "feature",
                "objectId": "invite_user",
                "relation": "member",
                "subject": {
                    "objectType": "pricing-tier",
                    "objectId": "pro"
                }
            },
            "isImplicit": "true"
        },
        {
            "objectType": "feature",
            "objectId": "advanced_search",
            "warrant": {
                "objectType": "feature",
                "objectId": "advanced_search",
                "relation": "member",
                "subject": {
                    "objectType": "pricing-tier",
                    "objectId": "pro"
                }
            },
            "meta": {
                "maxSearches": 5
            },
            "isImplicit": "true"
        },
        {
            "objectType": "feature",
            "objectId": "model_gpt4",
            "warrant": {
                "objectType": "feature",
                "objectId": "model_gpt4",
                "relation": "member",
                "subject": {
                    "objectType": "pricing-tier",
                    "objectId": "pro"
                }
            },
            "meta": {
                "maxTokens": 500
            },
            "isImplicit": "true"
        }
    ]
}

To learn more about the query endpoint, check out the API reference here.

That's all for day 2! We hope you're as excited as we are about today's announcements. Come back again tomorrow for day 3 as we launch a whole new batch of features and improvements! Also, be sure to join us on Slack to talk shop, give us your feedback, or tell us what you'd like us to work on next!

Share to Twitter

Share to Hacker News

Share to LinkedIn