Debug an Unexpected Result

Debug an unexpected result

You might find that the policy you've written has bugs and yields unexpected authorization decisions in your application. Oso Cloud provides two features that provide insight when debugging unexpected results: the Logs page and the Explain page. This guide will show you how to use them to find what’s going wrong.

As an example, imagine that in your app, a test user, Bob, has permission to edit a document called “Foo”, when in fact he should only have read access. You want to find out why that is. This guide will use Bob and the "Foo" document as an example, but you can use the same techniques to debug any unexpected result.

Find the unexpected result in the logs page

First, make sure that you can reproduce the error you’re seeing. Using the example of Bob and the "Foo" document, log in as your test user Bob and attempt to edit the document. Verify that the request reached Oso Cloud by visiting the Logs page in the dashboard:

View of the logs page in Oso Cloud dashboard, indicating Bob can edit the document Foo

You can see that, indeed, User:bob was determined to have edit permission on Document:foo in addition to read permission:

Close-up of the log indicating Bob can edit document Foo

This means that Oso did in fact receive the authorization query and returned allowed: true. So you’ve isolated the problem to your authorization model in Oso Cloud.


If you had not seen a corresponding log event in the Logs page, then Oso Cloud never saw that authorization. It’s possible that instead of incorrect policy logic or data, you are missing a call to oso.authorize()!

Use Explain to see why the result occurred

Once you’ve verified that the unexpected result is visible in Oso Cloud, use the Explain UI to diagnose why that result is occurring.

In the Logs page, click “Try this query” next to the unexpected result. This will open the Explain page and re-run the query that generated the log.

Logs page, highlighting a button to try the query

The Explain interface tells you why that action was allowed, including any facts that went into the decision and the rules that used those facts:

Explain page in Oso Cloud dashboard

In this example, there are two facts that granted Bob access to edit Document:foo:

Close-up of the facts that contributed to the query result

Bob is allowed to edit this document because it belongs to a folder, and that folder is marked as public! In the policy on the right, you can see which rules contributed to the decision:

Close-up of the policy rules that contributed to the query result

Using this information, you can often diagnose exactly why your combination of policy and data results in the action being allowed. In this example, you can see that users can perform any action on public folders (due to the wildcard _), which may not be what you intended. A possible fix may be to change the rule to only allow read actions on public folders. Another fix might be not to mark the Document:foo's folder as public. Either way, Explain has captured exactly why the result occurred.

Debug a false negative result

You can also use Explain to examine false negatives (denied actions that you expect to be allowed). The left hand side of the Explain interface lets you step through the “Attempts” that the policy engine made to find a permission. Each attempt corresponds to a different way someone can have permission to do something:

Explain page highlighting the failed query attempts

If you find an attempt that you expect to work, you’ll need to diagnose why the required facts do not exist in Oso Cloud. Perhaps you are missing a call to .tell in your backend, or your facts are using the wrong arguments.

If you do not find the attempt that you expect, it means your policy is missing a rule that allows a particular action — perhaps there is a rule that you need to add to the policy to get things working.

Talk to an Oso Engineer

If you’ve tried using the Logs and Explain pages, and you’re still stuck debugging an unexpected result, schedule a 1x1 with an Oso engineer. We're happy to help.

Get started with Oso Cloud →