Changelog
What's New

What's New with Oso Cloud?

Fallback GA, Local Authorization Enhancements, Watch Mode for Policy Tests, Write Logs

December 9, 2024

Fallback GA

Fallback is now generally available! With Oso's Fallback node, you can ensure your app stays operational in the event of a disruption to communication with Oso Cloud by using periodic data snapshots and offline capabilities to handle authorization requests seamlessly. For details on what’s new, check out our recent blog post (opens in a new tab)!

Local Authorization Enhancements

First came Local Authorization: Oso’s ability to make decisions based on data stored in your own database and avoid unnecessary data syncs. Now, we’ve made it even easier to build flexible and performant authorization workflows by adding Local Authorization support to features like context facts, the Query Builder, and recursion in the V2 SDKs (Node.js, Go, Python). Read more about how to use these tools in our recent blog post (opens in a new tab)!

Watch Mode for Policy Tests

We want Oso Cloud to enable teams to move fast, so we added “watch mode” for policy tests in the Oso Dev Server. When you add the --watch-for-changes flag, the policy will automatically reload and the policy tests will be rerun anytime file changes are detected, allowing you to continue developing without interruptions.

Logs of Writes to Oso Cloud

Applications have lots of moving and interconnected parts, making it complicated to isolate the root cause of an issue. We’ve made the debugging experience one step easier by adding a webhook integration which logs when Oso Cloud receives your data. This allows you to verify that your Oso Cloud environment has the data that you expect it to have at a given time.

Version Bumps

Other Improvements

Collapsible Sidebar

New around the Docs


New Oso clients, SSO support for Oso Cloud

October 22, 2024

V2 for Node.js, Python, Go clients

Whether you're managing authorization data or querying for authorized results, communicating with Oso Cloud should be straightforward. We’ve made this communication even more ergonomic by introducing simplified fact management APIs and powerful query builder APIs into our new Node.js, Python, and Go SDKs. We’ve also improved the developer experience for Node.js users by introducing the ability to generate TypeScript types from your Polar policy, ensuring that your application code aligns with your policy code. To read more about these improvements, check out our blog posts: Node.js (opens in a new tab), Python (opens in a new tab), and Go (opens in a new tab).

SSO Support for Oso Cloud UI

Growth customers can now sign in to Oso Cloud via SSO using authentication providers that support OIDC (such as Okta or Microsoft Entra). If you’re already using Google or GitHub and would like to switch to a new authentication provider, reach out and we can make that change for you!

New around the docs


Policy test fixtures

October 14, 2024

After a long hiatus, the Changelog is back!

Reuse data across multiple policy tests

Polar has a built-in test feature that lets you write and run unit tests on your Polar policy. Each unit test is made up of three components: a test name, a setup block containing a set of facts, and a set of literal-value queries. The facts listed in a setup block are only visible for the lifetime of that particular test. However, you can now reuse a set of facts (opens in a new tab) across multiple tests using a test fixture block.


Bug fixes & other improvements


Log Filtering, Demo Environment, Starter Policy & more

April 28, 2023

Log Filtering

Finding the right authorization log can be like finding a needle in a haystack. But now, with Oso Cloud, you can filter logs based on decision results, rule names, argument types, and ID values.


Demo Environment

Trying out new software is hard, so we're making it easier. Every new Oso Cloud user now gets a Demo environment pre-populated with a policy and facts. It's the perfect way to get started with Oso Cloud.


Starter Policy

Where do you start with a new authorization system? We've got you covered. Our Workbench now helps you define a starter policy based on your app's unique resource hierarchy and relationships. You'll be ready to integrate Oso Cloud into your app and start authorizing in no time.


Bug Fixes & Other Improvements

  • Released a sample application for Python and Node.js users allowing them to test Oso Cloud without using their own app
  • Added a global block to workbench to support the global role authorization pattern
  • Workbench now grants role inheritance on relations instead of granting permission inheritance on relations
    • ex: “editor” if “admin” on “parent” over “edit” if “admin” on “parent”
  • Updated and added copy explaining what facts are and how they’re used
  • Updated the add a fact modal requiring users to remember less syntax
  • Added a new view allowing users to view facts of a specific fact type based on their policy
  • Renamed navigation elements to align better with standard terminology
  • Renamed “sandbox” environments to “developer” environments
  • Documented policy concatenation for use in environments with multiple polar policy files

Bug Fixes & Other Improvements

March 31, 2023

  • Added a helper tool to the CLI that allows you to generate a policy from introspecting your database
  • Made it easier to distinguish between test errors and validation errors in the policy editor
  • Various usability improvements in Workbench
  • Added support for Linux arm64 platform for Golang client
  • Added M1 support for Ruby client
  • Fixed a bug where we allowed a user to try an unsupported polar feature in their policy (x = […]) and it failed
  • Fixed a bug where the vscode extension was not working for syntax highlighting and diagnostics in Linux
  • Dropped support for Python 3.6 (as it is end-of-life)

Production Admin Role, Fact Schema & Workbench Improvements

February 28, 2023

Admin & Member roles

As the number of developers in your organization touching your authorization configuration grows, it’s important to lock down the production Oso Cloud environment to ensure an accident doesn’t break something (even though you can perform a point-in-time recovery of your environment in seconds). To ensure you can avoid this risk we’ve added an Admin role with exclusive write access to the production environment, and a Member role with read-only access to production and read-write access to all other environments. If this functionality is important for you, check out the docs for modifying user roles.


Fact Schema

Oso uses small pieces of authorization data called facts to make authorization decisions. Oso infers type information about facts based on how the facts are used in your policy. Your application is responsible for providing these facts to Oso. In order to make it clear what types of facts you can add to Oso Cloud, you can use the new Fact Schema (opens in a new tab).


Workbench Improvements

Workbench is made to help you configure your authorization rules without needing to learn Polar. Now you can undo and redo any changes you make and we’ve also added policy tests to the Polar code it generates. Finally, we’ve begun adding inline help to the Workbench experience when you don’t know exactly what to include in your policy.

We’ll continue expanding on this in the coming weeks. Go check out the improvements to Workbench (opens in a new tab).


Bug Fixes & Other Improvements


Policy Testing, Workbench Beta, Global Roles, and Bug Fixes

January 26,2023

Policy Testing

When you’re trying to express something complicated in a new programming language you frequently need to validate that the code you’re writing will do what you want it to do. Well, now you can start writing Polar policies with a test-driven approach, or even configure your CI to reject policies with failing tests using Oso’s policy testing.


Workbench Beta

Understanding how to express complex authorization patterns in a new programming language can be challenging. You can read the syntax reference, look at sample policies and use standard libraries, but that requires you to do a bunch of work up front before you’re able to make progress on delivering the application functionality you need.

You can configure a new policy or add access controls for new resources in seconds by using Oso’s Workbench (opens in a new tab).


Global Roles

Sometimes you need a role that has some standard permissions everywhere in your application, like an internal superuser who needs to provide technical support. Now you can easily configure that with a Polar Building Block called Global Roles.


Bug Fixes & Other Improvements

  • Added a tooltip to the Explain page (opens in a new tab) next to Attempts
  • Added Explain output state to the URL so it can be navigated to
  • Added policy tests to builder patterns
  • Added steps to the getting started walkthrough to help new users get further during onboarding
  • Added an install page for the client SDK’s that includes instructions and examples for adding enforcement to your application
  • Added a caution banner when you’re editing your production environment’s policy
  • Added more descriptive page titles in the UI
  • Added role and permission keywords to shorthand rules
  • Added the ability for a user to implicitly declare facts inside a resource block
  • Fixed a bug where the docs search bar was returning broken links
  • Fixed a bug where certain actions would prevent policies from saving in the UI
  • Fixed a bug where colons were breaking explain output
  • Fixed a bug where under certain conditions adding a fact could crash the UI

Literals, Expiring Access and Other Improvements

December 29,2022

Literals

Sometimes when you’re authoring policy code it may feel easier to just refer to specific users, groups or other resources. Oso just made that possible by adding support for literals to Polar. Several users have requested this feature in order to add users to a superuser group and to reference a top level resource like the application itself.


Expring Access

There are many use cases when elevated privileges should not persist indefinitely. For instance, when support needs access to customer data or when users want to provide temporary access to project resources. Oso just made that possible with the addition of two new capabilities.

First, you can now access current unix time in an Oso policy which makes it possible for you to define a time period for access.


Second, Polar can now perform integer comparisons, which when combined with unix time, can determine if a resource has expired.


Bug Fixes & Other Improvements

  • Improved confusing UX on Explain
  • Made the "add a fact" modal input easier to use
  • Updated oso cloud python client to add support for python 3.11
  • Published revised “Get Started” material for the docs page
  • Fixed a bug where VS Code plugin complained when there were cross file references
  • Fixed a bug where an error repeated many times when submitting facts
  • Fixed a bug where the Actions endpoint returned partial results

Recovery UI (part 2) and Other Improvements

November 30, 2022

Recovery UI (part 2)

Continuing the recovery work completed in October, it’s now possible to recover a point in time snapshot of an environment to a new environment or rollback the current environment in place. It’s also now possible to see details of recent recoveries.


Visible Policy Metadata

It’s now easier to see what version of the policy you’re working on and when it was last updated in Oso Cloud right in the Policy interface.


Bug Fixes & Other Improvements

  • Added a Global Admin use case to the “Model Your App’s Authorization” doc
  • Automated billing so you don’t have to deal with monthly manual invoices
  • Wrote up detailed security and compliance documentation for prospects to use during the vendor approval process
  • Added several new cloud regions for deploying feature nodes as close to your workloads as possible, keeping latency very low for authorization checks
  • Improved monitoring and automation to keep the system exceeding availability and SLA commitments

Dashboard Redesign, Recovery UI, Product Portal & Hackathon

October 31, 2022

Dashboard Redesign

There are a handful of steps required to get an authorization service integrated into an application environment. Once configured and running, there are also a few key data points about the authorization service that are important to have access to after its been configured. With these things in mind the Dashboard page has been redesigned to initially provide reminders of the key milestones required to get the service configured. As the milestones have been achieved they change to display data points important for the function of the authorization service.


Recovery UI

Administering a production authorization service requires self-service recovery. During a disaster it can be best to recover an older copy in place, overwriting existing production files. Other situations may require a redirected restore to a different location. Oso Cloud’s new self-service recovery UI supports both of those operations.


Product Portal

It’s very important to ensure your authorization needs are being addressed by Oso. You now have a portal directly in the Oso Cloud UI for you to make enhancement requests, see what other users are asking for, and see what’s upcoming. Please make sure you check it out and provide inputs about how your needs could be better served.


Hackathon

We had a great hackathon in October. The team got together in our Manhattan office to celebrate the general availability of Oso Cloud and to work out some of our inner demons by hackin those thons right up. The team built a bunch of interesting things and we gave out some fantastically silly awards! Mike Cen received the, “Let’s Do The Time Warp Again” award for his hackathon project “Time Warp”. Here’s a brief description of the Time Warp project:

“One of the hardest parts of troubleshooting stateful applications is reproducing the state. In the context of Oso, that means recreating the exact policy and the exact set of facts. The Time Warp feature allows you to run an Explain query at any point in the past. How does it work? It uses the functionality we've been building for Recovery to create a temporary environment for the point in time, and the Explain query runs against that temporary environment.”


Stay tuned for some of these hackathon projects to make their way into the product. If you’d like to find out more about the hackathon projects you can join our community slack and look in the show & tell channel (opens in a new tab).

Bug Fixes & Other Improvements


Endpoint for Bulk Deletion + Insertion, Product Walkthrough & System Hardening

September 29, 2022

Endpoint for Bulk Deletion + Insertion

Changes to permissions such as elevating a user’s role can many times turn into a flurry of individual permissions deletions & insertions. In between those operations, the state of the user could become invalid downright nonsensical (for instance where a user can have 0 or 2 roles simultaneously) and developers would need to spend additional time building and testing behavior in these outrageous states.

In order to ensure you don’t have to spend the time building and testing those additional safeguards, and your users don’t have outrageous and downright nonsensical experiences, we introduced an API endpoint allowing you to do bulk deletions + insertions in one atomic transaction.


Product Walkthrough

When users are new to a tool they usually need a little time to acclimate to it. Unfortunately, without guidance, that means they bounce around looking at docs and clicking around in the UI until they think they’ve got it. That can be frustrating and take more time than it should. One of the best ways for new users to get used to something and learn the basics is to have an expert boil it down for them and tell them what they need to know.

Oso engineers have had to do this many times and have learned what new users need to understand when they’re experiencing the product for the first time. So, we finally asked Oso engineer, Vijay Ramamurthy, if he would put that experience in the product as a walkthrough.

In this first version we start with the basics about Oso Cloud, how it works and what you need to know to get started. So when a new user goes through this it’s like having Vijay standing behind them telling them what they’re looking at, what it means, and where to click next.


System Hardening

Authorization is a critical dependency for applications and it should be treated as such. Each organization has different standards for how they manage and monitor their critical dependencies and it can be a huge amount of work requiring a lot of meetings and additional tooling and a number of other things you probably don’t want to do as much as you want to be building features into your application. At Oso, our business is your authorization service, so we do a lot work behind the scenes to make sure your application always receives fast, secure authorization decisions. In September we did a huge amount of hardening work you won’t see but you will experience.

  • Validated and updated our runbooks to make sure they’re optimal and accurate.
  • Migrated infrastructure to more resilient platforms with better performance.
  • Built additional mitigations for potential reliability issues.
  • Built additional safeguards to protect against malicious users.
  • Made additional improvements ensuring your authorization experience is always low latency.
  • Made improvements to https://oso.statuspage.io/ (opens in a new tab)

Bug Fixes & Other Improvements

Global Oso Cloud UI

  • Removed the api key banner warning in the UI.
  • Made the docs link in the nav sidebar and facts page open in a new browser tab instead of in the same browser tab.
  • Added a nav button for the dashboard page in the admin console.
  • Bolded the text of the nav bar item you’re on to indicate what page you’re on.

Oso Cloud Dashboard

  • Added a link to the Dashboard in the nav bar.
  • Added a welcome message.
  • Removed the fact count metric.
  • Removed the instructions for adding api keys.
  • Removed the instructions for installing the cli tool.
  • Added a link to start the product walkthrough.

Oso Cloud Policy page

  • Changed the text on the “save” button in the UI to say “Save and Edit” to make it clear that the button was going to save the policy and take you to the Policy Editor.
  • Fixed a UI bug where the “skip to edit” button didn’t work unless there was a policy already saved in the environment.
  • Added a warning message when you click the “show builder” button in the policy editor when you’ve edited your policy code but haven’t saved it yet.
  • Fixed a UI bug where we didn’t return an error when a policy contained a not and instead would catch the error at query-time.
  • Fixed a bug where the polar validator in the policy editor would persist an validation error even after the offending code had been changed.

Oso Cloud Facts page

  • Fixed a UI bug where fact previews don’t disappear when you delete the fact you’re adding in the add a fact modal.
  • Persisted a fact example on the add a fact modal so users can continue to see the format of a fact while they type.
  • Removed the refresh button on the facts page and added polling with auto-refresh.

Oso Cloud Logging page

  • Fixed a bug in the “try this query” deeplinks in log entries where it wouldn’t let you retry the query.
  • Greyed out the button for “try this query” when a query contained context facts and added an explanation for why the button is greyed out.
  • Fixed UI bug where latency results on individual logs sometimes shows 0 instead of the actual query latency metric.
  • Added descriptive headers to columns in the logging interface.
  • Greyed out the button for “try this query” on log entries when a query contained context facts and added an explanation for why the button is greyed out.

Oso Cloud Settings page

  • Reorganized and decluttered the explanation text on the api keys tab of the settings page.
  • When viewing settings for the personal/sandbox organization, we now consistently display the users and environments tabs but include a message stating that these options are available in the paid tiers of Oso Cloud.

Client SDK’s & API

  • Published 1.0.0 versions of all supported Oso Cloud clients.
  • Improved the experience users have when we update clients; added a header to share what client was updated and what version it is, added an error message for the older version, and error message stating that sandbox accounts only support the latest version of the client, added api versioning for backwards compatibility, and made clients check for the latest version.
  • Made several improvements to go-oso-cloud sdk (opens in a new tab) (thank you Richard Mathieson (opens in a new tab)); added an OsoClient interface, made redundant exports private, fixed abbreviation casing, made client private.
  • Added some debugging (opens in a new tab) output to the node client to help identify networking issues (if you need this for other languages, let us know).
  • Api type cleanup
    • We used to have 3 different ways to specify facts and values in our http api. Getting facts used one format, query used another and authorize used a third one. In the client libraries we were converting all of those into a single format that the users used. This change was to just make all those apis take the same thing (something that looked like the type we were already converting it into) which cut out a ton of the translation code in the client libraries and let us just do that once in the service. For anyone using one of our client libraries it wasn't a breaking change since this is the api between our service and the client library, not between the client library and the user. It was only a breaking change if you were using the query endpoint without a client library (which nobody was when we did it).

VSCode extension

  • Syntax checking was updated to disallow not.
  • Added the ability to quickly switch between the two dialects of polar; i.e. when you get an error message, the error message will have an option to switch to the other dialect.

Documentation

Deprecations

  • Deprecated legacy API keys in favor of API keys that can be read-only or read-write

Query API, Logging, Environments Lifecycle, Policy Editor, API Keys

August 24, 2022

Use the Query API to ask Oso complex questions

Typical application authorization logic answers a single question: “Can this user do this action on this resource?” Evaluating that question is hardcoded into your application and answering different questions requires writing new code. As the logic changes all these evaluation paths need to be updated.

Oso takes a different approach and lets you declaratively model your authorization logic. This policy and data can then be used to answer multiple questions.

If you have a complicated question like -- "What are all the users that can do this action on this resource?" -- you can ask that question directly using Oso’s Query endpoint.

With Query, you can write a rule to answer any question you have. You can query custom and builtin polar rules in different ways depending on the information you have and the information you want.

Oso has other builtin endpoints for many common questions. Authorize lets you ask if a user can do an action on a resource. List gets you all the resources a user can do that action on. Actions gives you all the actions a user can do on a resource. And you can query the facts you've inserted into Oso Cloud with Get.

You are not limited to these and can ask anything you want with the Query endpoint.

Logs of Recent Authorizations

Logging in Oso Cloud is now enabled by default. Up until now, you had to string up your own logging system for debugging authorizations. Now, you can use the Logs page to see debugging information about every authorization request made by your application with 100% coverage.

Logs include all of the query inputs provided by your application as well as the results returned. Replay queries against your current policy and facts in the Explain view and see how rules in your policy contribute to the result.

With this tool, you can quickly identify why a recent request failed (or why it succeeded unexpectedly). The logs also show queries with wildcard arguments if you’re using the new Query API, along with a count of the results returned.


Creating and deleting environments

Environments management is self-serve! We've had support for multiple environments for a couple of months. However, environments, up until this point, were provisioned manually by Oso engineers.

Spinning up additional environments is important for ensuring your application authorization service matches your development or continuous integration workflow. Now, you can create and delete environments when you want them (or not) with self-service environment management right in the Oso console (opens in a new tab).


Edit your policy directly inside the Oso Cloud Dashboard

When using the dashboard to build your first Oso Cloud policy, you used to have to download the policy locally to then upload it into your Oso Cloud environment with oso-cloud policy. When you made changes to your policy, you had to use oso-cloud validate or install our VSCode extension to know if the policy was valid before uploading it.

To make it quicker and easier to get up and running with Oso Cloud, we’ve added a web-based editor so that you can view and modify your policy directly in the Oso Cloud dashboard. As shown in the screenshot below, the editor provides inline error messages as you write, just like our VSCode extension does.


Read-only API Keys

It's common for different parts of your application to need different levels of access to your authorization service. Some services might not need to modify any authorization-relevant data, they'll only need to perform authorize requests. You might also want to grant individuals, rather than applications, access to your authorization data for debugging and would prefer not to have to ask them to “promise to be extra careful not to mess with anything”.

Without a managed authorization service, you might need to then build this logic into your authorization itself, or rely on the security model of the system where you store your authorization-relevant data (usually a database). Both of these solutions can be painful to maintain over time.

With Oso Cloud, you can now solve this by issuing "Read-Only" API keys to apps/services/individuals. A "Read-Only" key can only be used to read facts and authorize actions, but not to write facts or update policies.


Changelog (July - August)

  • In the Explain UI: highlight the parts of the policy used in the current result to make it easier to trace through why a decision was returned.
  • Add new declare keyword which tells the validation logic to accept facts matching that form, even though it is not currently used in the policy.
  • Support inviting users to organizations (paid plans only)
  • Add Google as an authentication provider.
  • Return friendlier error message when we detect an unsupported policy.
  • Support adding facts in the UI so you can quickly test policies in development.
  • Fix fact deletion from the UI.
  • Check for newer versions when calling the CLI.
  • Add support for customizing the installation location of the CLI.
  • Persist connections in the client SDK's to reduce the number of network round-trips when authorizing.
  • Standardize client APIs around a simple data format to make it easier to use and understand how Oso uses application data.
  • Increase internal sqlite connection to improve the request throughput
  • Properly check HTTP status codes in the client to return better errors.
  • Set content length header to fix a bug causing proxied requests to fail.
  • Cache authentication information to reduce request latency.
  • Fix infinite redirect bug in the UI when a user is logged out.
  • Make it easier to read/parse the output of results from the CLI.
  • Fix a bug in the CLI installer, ensuring upgrades will work.
  • Better support unification in policies. Policies can now unify inputs, and will return an error message for cases that don't work.
  • Support looking up facts based on integer literals in the policy.
  • Update the list of potential facts on fact save, not receive. This fixes an issue in which sometimes facts wouldn't be used in a policy decision.

Explain Tool, Context Facts, GitCloud Sample App, Policy Examples

July 13, 2022

New Explain Tool

When you make an authorize request, Oso Cloud tells you if a user can do a certain action on a resource. You get back a true or a false. But what do you do if you don't get the answer you were expecting? It can be hard to debug problems with the policy which is why we've added a new tool to the dashboard. With the explain tool, you can see exactly why a query succeeded or failed. When a query is evaluated, the policy looks for the existence of certain facts. These could be has_role facts or has_permission facts or any other facts your policy uses. You can also see all the different possible sets of facts that would mean the user is allowed to do the action and which of those were actually found. It's a powerful debugging tool that we have used a lot ourselves and we know that it will help you too.

To get access to the explain tool, get started with Oso Cloud. (opens in a new tab)


Context Facts

We’ve heard from a lot of folks that authorization sometimes depends on information that is hard to migrate into the Oso Cloud data store. For example:

  • Deep resource hierarchies: you may wish to grant permissions for items that belong to an entity in your app, such as read access for issues in a repository if you’re building an app like GitHub. You may want to be able to make authorization decisions about such items while keeping your own database as the source of truth about these sorts of relationships between entities.
  • Claims from a user token: your users may get certain roles or permissions based on their authentication token (such as a JWT).
  • Request-specific context: if you want to protect resources based on IP addresses, or time of day, or other ephemeral request properties.

To address this feedback, we’ve added a new feature to Oso Cloud called “context facts”. Now whenever you ask Oso Cloud an authorization question, you can include contextual information for us to take into consideration when answering the question. Context Facts are available in the CLI (opens in a new tab) and all client libraries: Go (opens in a new tab), Node, (opens in a new tab) Python, (opens in a new tab) Ruby (opens in a new tab).


Tutorial: GitCloud Sample App

To help users understand how to add authorization using Oso Cloud in a real world app composed of multiple services, we created GitCloud (opens in a new tab), a GitHub/GitLab-like sample application.

For a tutorial on how GitCloud leverages Oso Cloud, see our latest doc on securing a real world app using Oso Cloud. (opens in a new tab) It covers the three main pieces involved in adding authorization: enforcement, modeling, and data management.


Updated Policy Examples

Last, but not least, we've taken a fresh coat of paint to our example policies featured in Modeling Building Blocks (opens in a new tab) and the Policy Builder (opens in a new tab).

We've expanded the sections covering the "Building Blocks" themselves to give a more conceptual overview of common policy structures. For example, we've described what we mean by Actors and Resources, how to use Roles in a policy, what a Resource Hierarchy is, and how to use generic Attributes.

All of these are reflected in the latest policy builder, making it even easier to get a full policy for your use case, with best practices built-in, in a matter of minutes!


Changelog (May - July)

  • Add validation that checks whether an inserted fact is valid, based on whether the current policy references it. This prevents incorrect facts from being inserted into the database.
  • Improve the performance of the batch authorize_resources endpoint by constructing a single query for all resources.
  • Fix a problem where a backlog of pending analytics events would gradually consume more resources and cause a performance degradation.
  • Add overlay facts implementations to all clients (see above).
  • Add types to the Node.js client SDK.
  • Reorganize the Polar Syntax documentation for easier discoverability.
  • Add a simple client-server versioning scheme.
  • Improved performance for most policies by 2x, and recursive policies by up to 500x.

How Oso Cloud Works, Facts-Based Approach, Multiple Environments

May 25, 2022

‍Docs: How Oso Cloud Works


We get a lot of questions about how Oso Cloud works, what you can do with it, and how it helps you organize authorization data and logic. To answer these, we put our ideas down in a new doc called How Oso Cloud Works (opens in a new tab).

Give it a read and get acquainted with our new managed product:

  • Where does Oso Cloud fit into your infrastructure?
  • What types of questions can your applications ask Oso Cloud?
  • How does Oso Cloud store data about resources in your applications?
  • How does Oso Cloud use permissions and resource data to make access decisions?
  • How should your applications insert and update data in Oso Cloud?

New Facts-Based Approach and APIs

While roles and relationships cover a wide range of authorization use cases, many companies have additional requirements involving some form of attributes. We’ve made it possible to represent attribute-based authorization so now Oso Cloud covers all commonly-seen authorization models:

  • Custom Roles: allow users to dynamically create and grant custom permissions to roles.
  • Default Roles: let users choose a default role for all members of their organization to inherit.
  • Public Resources: grant everyone read access to a resource that has been marked as public.
  • User Statuses: grant permissions only to users who are marked as active.
  • Toggles: conditionally grant permissions to roles based on a resource attribute

The Policy Builder (opens in a new tab) has examples of how to use these patterns in your Oso Cloud policies.

To support such a wide variety of ways to think about authorization, we switched from storingroles and relations to storing more general facts. Read more about facts in How Oso Cloud Works (opens in a new tab).

In moving to this more general facts-based approach, we will soon be removing the /roles and /relations endpoints in the Oso Cloud HTTP API (opens in a new tab) in favor of the more general /facts endpoint. We recommend updating to the latest versions of the Oso Cloud CLI and client libraries to prepare for this change.

Support for Multiple Environments

We’ve exposed an interface for managing multiple versions of your Oso Cloud policy and data to allow for better development and testing workflows. Just as you might have both a staging and production database, now you can have a staging and production authorization engine.

Each environment in Oso Cloud uses a different API key, which you can access (and reset!) from the web interface (opens in a new tab). This means that your application code doesn’t need to know what environment it’s accessing, you can just treat your API keys the same way you treat other configuration values that vary across deployments (such as your database handles).


Additionally, backups can be accessed across environments, which makes it possible to copy data from one environment to another. This can make maintaining dev/prod parity much easier. You can read more here.

Changelog (April - May)

  • Released the Oso Cloud SDK for Ruby (opens in a new tab).
  • Updated the dashboard (opens in a new tab) to provide an overview of the current state of your Oso Cloud instance. This page now includes a summary of the data stored, and log of recent authorizations. If you haven’t yet tried out Oso Cloud, the dashboard will give you some simple ways to get started.
  • Improved the query evaluation logic so that allowed decisions will often shortcut evaluation and return faster decisions.
  • Built a load testing harness, and used this to measure best and worst case latency and throughput. We’ll share the results of this soon.
  • Added a bulk deletion API so that bulk operations can be handled in a single network request.
  • Added read/write APIs for the fact-based approach (see above), which also permit passing in wildcard parameters to fetch multiple facts.
  • API documentation (opens in a new tab) autogenerated from our OpenAPI schema to make it easier for anyone developing against the Oso Cloud API directly.
  • Added a bulk authorization API authorize_resources (opens in a new tab) so that applications can save the network latency of making multiple round-trips when they know ahead of time the set of resources that need to be authorized.
  • Standardized errors across all endpoints to return a JSON object with an error message field to make it easier to handle errors consistently in the client.

Oso Cloud Sandbox, Policy Builder, Guide: Add Oso Cloud to your App

April 26, 2022

Oso Cloud is now in public beta. You can use your GitHub login to get access to the Oso Cloud Sandbox, a test environment that supports all the latest features. We’re frequently rolling out new features to the Sandbox, like our recent web and command line interfaces and client library updates (currently in Python, Go, and Node.js). Go to the Oso Cloud Sandbox to get your API key, and run through our quickstart guide to get started. For production access, reach out.

Policy Builder

Many developers start by trying to understand what authorization model they have. All they’ve heard of is “roles” or “attributes.” Oso Cloud’s new Policy Builder gives you more structure than that by giving names to common patterns, like “org charts,” and showing you how to model those patterns in Oso. The Policy Builder is a tool that helps you try out different models that might apply to you and model them using Oso:


Note: for more detailed documentation on these patterns, you can also read our Authorization Building Blocks guide.

Guide: Add Oso Cloud to your App

Before adopting Oso Cloud, you’ll want to get a feel for what the process of adding it to your app looks like. That’s what this guide on adding Oso Cloud to your app is for — it shows you how to use the Oso Cloud client libraries (Python/Node/Go) to perform authorization checks in your app. The guide walks you through updating authorization data and enforcing authorization decisions in the language of your choice.


To get started adding Oso Cloud to your app, read the guide (opens in a new tab).

Oso Cloud Dashboard

We’ve built a new dashboard for Oso Cloud! It now summarizes the data you’ve added (e.g., roles and relations) and also logs for recent authorization requests to your Oso Cloud instance.


Oso Cloud Audit Logs for Authorization Requests

We recently spoke with an Oso user who said: “Authorization systems are so tricky – they never tell you when they’re working.”

Not anymore!

Now you can see that Oso Cloud is authorizing (or denying) requests in real time. The Logs page contains all recent authorization logs for authorize and list requests to your Oso Cloud instance. (For the Sandbox, we persist the last 512 logs for you. There’s no limit for production.)


Changelog (March - April)

  • Default allow rule so most policies can skip the boilerplate
  • Documentation for building blocks and patterns (opens in a new tab)
  • Support for multiple tenants in a single Oso instance for use in the sandbox
  • Enable using the “in” operator in policies when the right-hand side is a list of strings
  • Dashboard page to show CLI usage and for retrieving API credentials
  • API for monitoring recent requests
  • Stats API to get a summary of data stored in Oso Cloud
  • Prevent infinitely recursive rules from timing out by adding a limit — recursive rules will currently work up to a maximum of 128.
  • Rolling backups of data stored in Oso Cloud to S3
  • API for creating and restoring specific snapshots
  • Internal data model changes to make it possible to store more kinds of data, and support more authorization models — watch this space!
  • Add CLI option --fail-on-deny to the authorize command, so the CLI can be used in scripting workflows
  • CLI command to see recent requests as JSON
  • OpenAPI schema and UI explorer for use in language without an existing Oso SDK
  • Additional reference documentation
  • Modified API token format to support secret scanning measures
  • Guide for adding Oso to an application
  • Fixed a bug causing internal server errors before validating the policy
  • Consolidated validation logic between the CLI and Oso cloud so that policies that validate correctly in the CLI will work in the cloud
  • Integrated an OpenAPI fuzzer to find any other error cases that aren’t currently handled

Authorization Model Visualizer, Oso Cloud Docs and Changelog

March 23, 2022

Here’s the latest on Oso Cloud:

Visualize Your Authorization Model

One of the hardest problems in authorization is modeling. Should you represent this as a role or a relationship? How do you represent what’s going on in your app as authorization logic? To help you understand your model better, we’re experimenting with a model visualizer.

Today, the visualizer takes your Oso policy and displays it as a graph. For instance, this is what our GitClub application looks in the visualizer:


The visualizer currently supports resource blocks, which is how you model role-based access control (RBAC) in Oso. If you want to see what the visualizer would look like for your model, set up a 1x1 with the engineer who built it.

Oso Cloud Docs

Oso Cloud docs are live.


For an Introduction to Oso Cloud, Quickstart, and API docs go to: https://cloud-docs.osohq.com/ (opens in a new tab).

Changelog (Feb - Mar)

  • APIs and CLI commands for introspecting data stored in Oso
  • CLI command to fetch latest policy
  • Support for global roles, e.g. global superadmins
  • Data validation against policy spec
  • Custom Polar predicates
  • Stats endpoint to view metrics for data stored by Oso
  • Support for complex compositions of relationships
  • Token-based authentication
  • Oso Cloud clients for Go, Node, Python & Ruby
  • Support for multiple environments
  • CLI binary distributed via CDN

Quickstart & Next Steps

Oso Cloud is in closed beta, but we have docs available here (opens in a new tab). If you’d like to learn more about Oso Cloud or try it out, set up a 1x1 with our engineering team (opens in a new tab).


Intro to Oso Cloud, Quickstart and Changelog

February 15, 2022

We’ve been thinking about Oso Cloud for 2+ years. Here’s a preview while it’s in closed beta.

What is Oso Cloud

Oso Cloud is a fully-managed authorization service. You use it to provide fine-grained access to resources in your app, to define deep permission hierarchies, and to share access control logic between services in your backend.

As with the open source Oso library, you write policies in our declarative authorization language, Polar (opens in a new tab), to describe who is allowed to do what in your app, e.g., an admin role at an organization always grants users write access to resources that the organization owns. Oso can then efficiently use those policies to make authorization decisions.

But in contrast to the library, Oso Cloud lives separately from your applications, and stores its own data:


An Oso Cloud server exposes three APIs:

  1. The write API, which updates authorization data (or keeps it in sync with your application).
  2. The check API, which makes authorization decisions.
  3. And the policy API, which updates your policy code.

We provide client libraries to integrate Oso Cloud with your application, as well as a CLI for development and testing.

Changelog (Nov - Feb)

  • Add bulk load endpoints for role & relation data
  • Add delete & read endpoints for data management
  • Implement CLI frontend
  • Deploy Oso service to cloud for early users
  • Add policy validation for supported features
  • Run server in watch mode, reload when policy changes
  • Integrate new polar-core into service
  • Add tracing
  • Error on unsupported policies
  • Expose CLI for adding/deleting roles/relations
  • Make unsupported Polar features (in policy) parse-time errors

Quickstart & Next Steps

Oso Cloud is in closed beta, but we have a preview Quickstart Guide available here (opens in a new tab). If you’d like to learn more about Oso Cloud or try it out, set up a 1x1 with our engineering team (opens in a new tab).

Oso Cloud CLI