Best Practices for Polar Modeling
When modeling your authorization policy in Polar, we have a few best practices.
The Golden rule
Concentrate the core logic of your policy into a small number of rules. From there, you might discover that the bulk of the policy contains permutations of those core patterns.
General guidance
-
Start simple and evolve over time.
For example, start with coarse-grained authorization by implementing most rules at the highest resource level (e.g.
resource Organization
for multitenant apps), and introduce granular resources and permissions only as needed. -
As you expand the model, include inline documentation.
-
Identify abstractions and leverage them quickly.
If there are multiple authorization rules that all seem to follow a similar shape (e.g. rely on the same set of 2+ facts), that can be an indicator of a missing abstraction in the authorization policy.
Identifying these common patterns can help further understanding of what the core authorization model is, as well as reduce repetition.
Naming
Align the names of everything in your authorization model to your application, including API calls.
For instance, many of our code samples use "read"
and "write"
as permission
names, but if your API uses GET
and POST
, "get"
and "post"
might be more
appropriate.
Multiple policy files
Oso's tooling lets you maintain your policy spread across many .polar
files.
When you deploy them,
all of the files are concatenated together and used as a single policy for your
environment.
You can leverage this feature to simplify policy management. We recommend structuring the policies to mirror your authorization model, for example:
- Maintain the core policy model under
policy.polar
, containing common resources likeOrganization
s. - Use additional files for individual resources that extend the policy, e.g.
orders.polar
for anOrder
resource.
Additionally, all of your .polar
files should be managed through version
control, just as the rest of your software.
Consider authorization data
If you are using centralized authorization data stored in Oso Cloud, minimize the number of facts your app must insert or delete upon any given change.
Tests
- Test all of your policy's core logic
- Test intermediate states as well as the end results
- Avoid enumerating all permutations of roles + permissions