Polar Modeling Best Practices

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 like Organizations.
  • Use additional files for individual resources that extend the policy, e.g. orders.polar for an Order 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
Authorization Data