Protecting a Blog Application

This guide walks through the steps required to deeply integrate an application with Authzed or SpiceDB. Not all software requires this level of integration, but it is preferable for greenfield applications or applications that are central in an architecture with multiple services.

Instead of introducing an unfamiliar example app and altering various locations in its code, this guide is written such that each step is a standalone snippet of code that demonstrates an integration point and finding where those points exist in your codebase is an exercise left to the reader.

Prerequisites

One of:

• An Authzed (opens in a new tab) Permission System and associated API Token with admin access
• A running instance of SpiceDB (opens in a new tab) with the configured preshared key for SpiceDB:

# Using the binary
spicedb serve --grpc-preshared-key "t_your_token_here_1234567deadbeef"
 
# Using Docker
docker run --rm -p 50051:50051 authzed/spicedb serve --grpc-preshared-key "t_your_token_here_1234567deadbeef"

Installation

The first step to integrating any software is ensuring you have an API client.

Each tool is installed with its ecosystem's package management tools:

brew install authzed/tap/zed
zed context set blog grpc.authzed.com:443 t_your_token_here_1234567deadbeef

Defining and Applying a Schema

Regardless of whether or not you have a preexisting schema written, integrating a new application will typically require you add new definitions to the Schema.

As a quick recap, Schemas define the objects, their relations, and their checkable permissions that will be available to be used with the Permission System.

We'll be using the following blog example throughout this guide:

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

This example defines two types of objects that will be used in the permissions system: user and post. Each post can have two kinds of relations to users: reader and writer. Each post can have two permissions checked: read and write. The read permission unions together both readers and writers, so that any writer is implicitly granted read, as well. Feel free to start with design to modify and test your own experiments in the playground (opens in a new tab).

With a schema designed, we can now move on using our client to apply that schema to the Permission System.

zed schema write <(cat << EOF
definition user {}
definition post {
    relation reader: user
    relation writer: user
    permission read = reader + writer
    permission write = writer
}
EOF
)

Storing Relationships

After a permission system has its schema applied, it is ready to have its relationships be created, touched, or deleted. Relationships are live instances of relations between objects. Because the relationships stored in the system can change at runtime, this is a powerful primitive for dynamically granting or revoking access to the resources you've modeled. When applications modify or create rows in their database, they will also typically create or update relationships.

In the following example, we'll be creating 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 (opens in a new tab) relationships, but those are not as immediately useful for an empty permission system.

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

Checking Permissions

Permissions Systems that have stored relationships are capable of performing permission checks. Checks do not only test for the existence of direct relationships, but will also compute and traverse transitive relationships. For example, in our example schema, writers have both write and read, so there's no need to create a read relationship for a subject that is already a writer.

The following examples demonstrate the transitive property of checks:

zed permission check post:1 read  user:emilia   --revision "zedtokenfromwriterel" # true
zed permission check post:1 write user:emilia   --revision "zedtokenfromwriterel" # true
zed permission check post:1 read  user:beatrice --revision "zedtokenfromwriterel" # true
zed permission check post:1 write user:beatrice --revision "zedtokenfromwriterel" # false