Skip to main content

Protecting Your First App

Work in Progress

This page may be updated frequently as we are actively working on updating our documentation with our current Authzed terminology.

Introduction#

This guide walks through defining a permission system for a very simple blog application.

Each section demonstrates how to use the API to perform the required step and the final section demonstrates these APIs calls combined into one end-to-end integrated application.

Prerequisites#

Installation#

In order to interact with Authzed, you'll need an Authzed API client.

In addition to client libraries, the zed command line tool can be used to interact with the API from macOS or Linux shells.

Each tool is installed with its native package management tools:

brew install --HEAD authzed/tap/zed

Defining and Updating a Schema#

The first step in a new permissions system is to apply a Schema.

Schemas define the Objects in a Permissions System.

Objects have two kinds of properties: Relations to other Objects and Permissions.

Relations have types that specify which Objects can have that Relation.

Permissions are computed from combining Relations with set operations (union, intersection, exclusion).

The following is a basic Schema for a blog:

definition blog/user {}
definition blog/post {  relation reader: blog/user  relation writer: blog/user
  permission read = reader + writer  permission write = writer}

This example defines two types of Objects that will be used in the Permissions System: Users and Posts. Posts can have two relations to Users: reader and writer. Posts can have two permissions checked: read and write.

Notice that the read permission unions both readers and writers. By doing so, you avoid having to perform multiple checks for all the relations that should have access to an Object.

With the basics down, you can explore building your own schemas on the Authzed Playground.

Now apply the schema using the command line or a client library:

zed schema write blog_permissions.zed

Creating Relationships#

Once a Schema has been applied, the next step is to create Relationships the follow that Schema. Relationships are instances of a Relation between two Objects.

Create two relationships: one making Emilia a writer of the first post and another making Beatrice a reader of the first post. You can also touch and delete relationships, but those are not as immediately useful for an empty permission system.

note

The API version of the client in the code examples has switched from v1alpha1 to v0. Currently, the Schema API is the only API available in v1alpha1.

zed relationship create user:emilia   writer posts:1zed relationship create user:beatrice reader posts:1

Checking Permissions#

Permissions Systems that have existing relationships can perform Permission checks. Checks determine whether an Object has permission to perform an action on another Object. This most commonly takes the form of Users checking their access to perform CRUD operations on a resource in an application.

The following demonstrates exhaustively checking all the permissions for Emilia and Beatrice on the first post; notice that Emilia has read access implicitly through the writer relation:

zed permission check user:emilia   read  posts:1 # truezed permission check user:emilia   write posts:1 # truezed permission check user:beatrice read  posts:1 # truezed permission check user:beatrice write posts:1 # false

End-to-End Example#

This document has covered independent usage of each API call needed to integrate an application, but it has not shown the integration points in a typical application. To see examples and learn more about where these APIs should be called within your application, see the following:

Resources for end-to-end examples include: