Often, the best examples of how to do something with a tool are in situ. It's great to watch videos and read docs to develop a mental model, but it's often most instructive to just see what tools do. I suspect this is why, when reading documentation, developers often skip past the carefully crafted conceptual information to find the code samples.
Not all demonstrations of a library are the same, either––quickstarts and code snippets are often light on context; sample apps are often built to demonstrate a single feature. When picking up a new tool, I sometimes want to use the API in a manner that seems reasonable to me at that time…but when I consult the docs, my imagined use seems totally ignored. I suspect this is because the aims of the reader are sometimes more complex than the writer envisioned.
We strive to build Oso with as much empathy as possible, making intuitive APIs and providing clear instruction––but, invariably, users come up with questions about how to actually use Oso in something as complex as a modern web app.
To proactively answer more of those questions, we’ve been investing in more realistic and complex reference materials, which we want to make sure folks can leverage including:
- An iterative adoption guide to help users replace homegrown authorization tooling bit by bit
- Reference applications that demonstrate how to use Oso Cloud in complex applications.
Guide to Iteratively Adopt Oso Cloud
One of Oso’s enormous benefits is its flexibility. We aim to meet developers where they are and make adopting Oso for authorization as seamless as possible. One of the north stars we aim for is the ability for teams to iteratively adopt Oso into their application. If you have an existing authorization solution, you shouldn’t have to rip the entire thing out to start using Oso.
To ensure that the processes we envisioned and the tooling we provided could actually rise to this challenge, two of our engineers reality tested and thoroughly documented the process, which you can find in our docs as Iterative Adoption of Oso Cloud.
While not necessarily a breezy task, the guide shows you how to do something very complex: take an existing application and carefully replace its home-grown authorization service with Oso Cloud. The guide covers:
- Modeling your existing authorization code in an Oso policy
- Using your application’s existing data to validate that the new Oso policy and your current implementation provide the same guarantees
- Upgrading your endpoints to solely rely on Oso Cloud
A big hats off to Greg Sarjeant and Jordan Killpack for making the difficult and weedy into something linear and tractable.
Reference Apps
While many pieces of software include sample applications with simple uses of their API, the snippets often lack the sophistication required to help users tackle realistic problems. To remedy this, we conceived of the idea of a “reference” app.
We aim for these apps to go a few steps beyond a standard sample app both in terms of complexity, as well as provided documentation. We haven't taken them quite as far as using the literate programming paradigm, but we aim to be closer to that than the standard doc strings.
With that, we’re pleased to show you the first reference app on GitHub.
It's a multi-tenant Google Drive-like file sharing platform built using:
- Oso's local authorization (powered by PostgreSQL)
- Next.js with server actions + TypeScript
- Simple orchestration through Docker compose
In the application itself, you'll find:
- Fully documented Oso configuration, including a complex policy
- Realistic examples of using role-based access control (RBAC), relationship-based access control (ReBAC), as well as attribute-based access control (ABAC)
- Simple GUI with first-class impersonation, making it easy to get hands-on experience with the impacts of authorization on the application state
For details about how to get a feel for the application, see its README over on GitHub.
Coming up
We have a few things in the works related to this project, including:
- More reference apps targeting different use cases
- Updated example as our APIs continue maturing
If you have any feedback, feel free to file issues in the repository or let us know in the Oso Community Slack.
