The Aserto team has been hard at work improving Topaz and the Aserto SaaS platform. We’re excited to share a few of the new product features. Let us know what you think!

TLDR: Authorization templates built around common permissioning models provide you a great starting point for your own model. Assertions make it easy to define and regression-test the validity of your authorization model.

Authorization Templates

Authorization templates are a great way to start your authorization journey. We currently have six authorization templates, with more on the way. Best of all, they can be installed either from the Topaz CLI or via the Aserto Console.

Here’s a rundown of the current set of templates and which scenarios we recommend them for.

End-to-end samples

Todo application

This template contains a simple manifest that defines Todos using the resource object type, and a custom policy that follows our “REST” convention, defining a module for each API that the Todo backend exposes. The backend is offered in six different programming languages - Typescript, Python, Go, Java, .NET, and Ruby. Finally, it contains a Todo frontend application written in React, hosted here, which provides an easy way to visualize and test the application.

Use this template to learn how to build authorization for a simple and familiar end-to-end application in the language of your choice.

PeopleFinder

This template contains an end-to-end sample for a corporate directory application. It comes with three different policies representing different authorization styles - RBAC, ABAC, and ReBAC. It’s a great way to understand the differences between these authorization models.

Each policy implements the admin and viewer roles (either via group membership or attributes): admins can do everything, and viewers can view everyone and update their own personal information. In addition, the ReBAC version of the policy enables managers to update their reports’ title and department, demonstrating how to combine the styles.

The application that comes with this end-to-end sample is a monorepo that contains a React frontend and a node.js backend, which can easily be deployed to Netlify.

This is a great place to start if you want to understand the difference between different authorization models, and the value of switching authorization models without having to redeploy the application!

Authorization Models

Simple RBAC

The Simple RBAC model is the simplest ReBAC-style template we offer. Its manifest defines a resource object type, with owner, writer, and reader relations. Much like the rest of the ReBAC-style templates, this template uses the canonical policy-rebac OPA policy which simply delegates to the ReBAC ds.check built-in to determine whether a user has a permission on a resource.

Like the other ReBAC templates, it uses the Citadel demo IDP, which contains 5 users modeled after the Rick and Morty cartoon. It also contains a set of resources, which are connected to various users through the admin, writer, and reader relations.

Similar to the other ReBAC templates, it has a backend API implemented in six different languages, accessible via the Aserto SaaS. The Aserto Console also has a Test Modal, which can be used to formulate curl requests to make calls to the various endpoints the backend exposes, using different user and resource combinations.

This is a great template to use if you have a simple RBAC model without any nested resources.

Google Drive

Like the other ReBAC templates, the Google Drive template uses the canonical ReBAC policy (policy-rebac) and the Citadel demo IDP.

The Google Drive manifest contains two object types - folder and doc. They both have a parent relation whose target is a folder. The can_read, can_write, can_share, and can_delete permissions can be directly assigned on either the doc itself or on a folder in its parent hierarchy, and that permission will automatically be inherited, much like in Google Drive.

The template also comes with sample folders and documents, and the Console offers a backend API implemented in six different languages, as well as the Test Modal which can be used to formulate curl requests to the various endpoints using different user and resource combinations.

Use this template as a starting point if you have a hierarchical, nested model for resources that resembles Google Drive.

Slack

The Slack manifest contains two object types - workspace and channel, where a channel lives in a workspace. Permissions such as can_read, can_write, can_comment, and can_delete can be granted through either a channel or its parent workspace.

Like the other templates, this one comes with the same workspace and channel resources that are related to the various demo IDP users and the same quickstart experience in the Console.

Start with this template if you have a two-level resource model.

GitHub

GitHub is our most comprehensive authorization model. It contains organization, team (which can be nested), and repo object types. Permissions are granted through any of these constructs. We have a whole blog post dedicated to it!

Use this template if you have a multi-level hierarchy, where organizations (tenants) are at the highest level, but teams can be arbitrarily nested (like groups) underneath each organization.

Authorization Templates in Topaz

Use the topaz templates list command to list the available authorization templates:

topaz templates list

  NAME          DESCRIPTION                                                        DOCUMENTATION
  gdrive        Authorization template for nested folders and documents            https://docs.aserto.com/docs/quickstarts/gdrive/overview
  slack         Authorization template for workspaces and channels                 https://docs.aserto.com/docs/quickstarts/slack/overview
  github        Authorization template for repositories, organizations and teams.  https://docs.aserto.com/docs/quickstarts/github/overview
  peoplefinder  Corporate directory end-to-end sample                              https://docs.aserto.com/docs/getting-started/peoplefinder/peoplefinder-overview
  todo          Todo application end-to-end sample                                 https://docs.aserto.com/docs/quickstarts/todo/overview
  simple-rbac   Simple RBAC authorization template                                 https://docs.aserto.com/docs/quickstarts/simple-rbac/overview

Use the topaz templates install command to install an authorization template:

topaz templates install gdrive

Installing this template will completely reset your topaz configuration.
Do you want to continue? (y/N) y
>>> stopping topaz...
>>> configure policy

certs directory: /Users/ogazitt/.config/topaz/certs

  FILE            ACTION
  gateway.crt     skipped, file already exists
  gateway-ca.crt  skipped, file already exists
  gateway.key     skipped, file already exists
  grpc.crt        skipped, file already exists
  grpc-ca.crt     skipped, file already exists
  grpc.key        skipped, file already exists
policy name: gdrive
>>> starting topaz...
e0c5526310ff4cc69970df50dd5a4c926ffb05ad68870c67d4b30b1eb1d68230

WARNING: delete manifest resets all directory state, including relation and object data
>>> delete manifest
>>> set manifest from /Users/ogazitt/.config/topaz/model/manifest.yaml
>>> importing data from /Users/ogazitt/.config/topaz/data
        objects 41
      relations 69
0001 check            PASS  folder:root#owner@user:beth@the-smiths.com [true] (10.178417ms)
0002 check            PASS  folder:root#can_read@user:beth@the-smiths.com [true] (769.292µs)
0003 check            PASS  folder:root#can_write@user:beth@the-smiths.com [true] (577.791µs)
0004 check            PASS  folder:root#can_share@user:beth@the-smiths.com [true] (551.709µs)
0005 check            PASS  folder:root#can_read@user:rick@the-citadel.com [false] (580.292µs)
0006 check            PASS  folder:root#can_write@user:rick@the-citadel.com [false] (710µs)
0007 check            PASS  folder:root#can_share@user:rick@the-citadel.com [false] (879.5µs)
…
Test Execution Summary:
-----------------------
total:   187
passed:  187
failed:  0
errored: 0

Authorization Templates in the Aserto Console

To initialize an authorization template in the console, go to the Policies Tab and click the Create an instance button.  Click the first option - Create a policy instance by instantiating a template. Then select one of the authorization templates. This will replace your existing model and any data you have in the directory with the contents of the new template.

Assertions

Testing an authorization model is one of the most important aspects of developing an externalized authorization strategy. Assertions can be thought of as “unit tests” for an authorization model: each assertion contains a fully-specified check call, and an expected outcome.

A few of the templates mentioned in the previous section also install a set of assertions. Inspecting and executing them is a good way to get started with this feature.

Assertions in Topaz

Topaz has a set of commands for creating and executing assertions.

topaz test template outputs a JSON template that shows how to use the assertion types. The check assertion type issues a Check call to the directory with the object_type, object_id, relation, subject_type, and subject_id tuple. The check_decision type issues an Is call to the authorizer with the payload provided.

topaz test template
{
  "assertions": [
	{"check": {"object_type": "", "object_id": "", "relation": "", "subject_type": "", "subject_id": ""}, "expected": true},
	{"check_relation": {"object_type": "", "object_id": "", "relation": "", "subject_type": "", "subject_id": ""}, "expected": true},
	{"check_permission": {"object_type": "", "object_id": "", "permission": "", "subject_type": "", "subject_id": ""}, "expected": true},
	{"check_decision": {"identity_context": {"identity": "", "type": ""}, "resource_context": {}, "policy_context": {"path": "", "decisions": [""]}}, "expected":true},
  ]
}

topaz test exec will execute a set of assertions in a JSON file (by default, ./assertions.json). The templates that have assertions install them in $HOME/.config/topaz/assertions.

topaz test exec -i ~/.config/topaz/assertions/gdrive_assertions.json
0001 check            PASS  folder:root#owner@user:beth@the-smiths.com [true] (3.745667ms)
0002 check            PASS  folder:root#can_read@user:beth@the-smiths.com [true] (965.417µs)
0003 check            PASS  folder:root#can_write@user:beth@the-smiths.com [true] (535.583µs)
0004 check            PASS  folder:root#can_share@user:beth@the-smiths.com [true] (609.667µs)
0005 check            PASS  folder:root#can_read@user:rick@the-citadel.com [false] (686.041µs)
0006 check            PASS  folder:root#can_write@user:rick@the-citadel.com [false] (607.917µs)
0007 check            PASS  folder:root#can_share@user:rick@the-citadel.com [false] (664.041µs)
0008 check            PASS  folder:root#can_read@user:morty@the-citadel.com [false] (513.042µs)
...

Running topaz test exec in CI is a great way to ensure that any changes to the model are compatible with the expected values specified in the test suite.

Assertions in the Aserto Console

Running Assertions in the Aserto Console is a convenient way to store a test suite as part of a tenant / organization, and execute it against the current model. Navigate to the Assertions Tab in the console, and click the Add assertion button to add assertions to your tenant. The modal has a convenient way to duplicate assertions, so that you can easily add more than one at a time.

Once you’ve added assertions, you can edit or duplicate them from within each assertion’s context menu.

Finally, to execute assertions, simply click the Run button either at the top (to execute all or selected assertions), or the one next to each assertion to run an individual assertion.

Summary

The Aserto team has been hard at work over the last few weeks, delivering features that significantly enhance and simplify the developer experience around creating and testing authorization models. Everything we build is meant to make adding fine-grained authorization easy for developers like yourself, so any and all feedback you have about Topaz and Aserto would be widely appreciated.

Simply drop us a line a hello@aserto.com, send us a message on our community Slack, or use our contact page.

Happy hacking!