Upgrading to 0.20

Oso’s 0.20 release is larger than usual as it includes a number of new features around authorization modeling, enforcement, and data filtering.

To migrate to 0.20 from 0.15, the previous stable release, follow the steps in this guide.

Parenthesize or operations

The or operator has had its precedence lowered to be consistent with other programming languages. Existing policies using or should be updated where necessary to group or operations using parentheses:

To migrate, rewrite:

foo(a, b, c) if a and b or c;

as:

foo(a, b, c) if a and (b or c);

We have temporarily made policies that combine and and or without parentheses raise warnings in order to avoid silent changes. To silence the warning, add parentheses.

Consolidate load_file() calls into a single load_files() call

As of 0.20, all Polar policies must be loaded in one fell swoop. To facilitate this, Oso.load_file() has been deprecated and replaced with Oso.load_files() , which loads multiple Polar policy files at once.

Continued use of load_file() will result in deprecation warnings printed to the console. load_file() will be removed in a future release.

To migrate, rewrite:

oso.load_file("main.polar")
oso.load_file("repository.polar")

as:

oso.load_files(["main.polar", "repository.polar"])

Migrating from Polar Roles to the new resource block syntax

The 0.20 release introduces resource blocks for expressing role-based (RBAC) and relationship-based (ReBAC) access control logic in a concise, readable syntax.

For a taste of the new resource block syntax, see the Build Role-Based Access Control (RBAC) guide.

The previous Polar Roles feature has been removed, and we encourage all users to upgrade to the new syntax, which supports a superset of the functionality of the previous feature.

If you are using Polar Roles with a previous version of Oso and want to upgrade to the 0.20 release, please reach out via Slack or schedule a 1-on-1 with an engineer from the core team.

Migrate from allowed?() to authorize()

The 0.20 release introduces Oso.authorize() , a new method that supplants Oso.allowed?() as the preferred API for resource-level enforcement.

The methods' return values are different: allowed?() returns a boolean and expects you to translate false into an authorization failure, but authorize() raises an Oso authorization error, which you can translate into your own error type.

To migrate, rewrite:

unless oso.allowed?(actor: "Ariadne", action: "assist", resource: "Theseus")
  # handle authorization failure (probably by raising an error)
end

as:

begin
  oso.authorize("Ariadne", "assist", "Theseus")
rescue Oso::ForbiddenError, Oso::NotFoundError
  # handle failures (probably by raising your own error types)
end

Connect with us on Slack

If you have any questions, or just want to talk something through, jump into Slack. An Oso engineer or one of the thousands of developers in the growing community will be happy to help.