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:
You can see that, indeed, User:bob was determined to have edit permission on Document:foo in addition to read permission:
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.
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:
In this example, there are two facts that granted Bob access to edit Document:foo:
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:
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:
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.
Verify that Oso Cloud is receiving writes
If your authorization logic is correct and you have confirmed that you are receiving the expected authorization attempts, then your authorization data may be out of sync between your application databases and Oso Cloud. You can verify that the data that you expect is in place by using the oso-cloud get CLI command to find expected facts.
If Oso Cloud is missing data that you expect, you can set up a webhook to confirm that Oso Cloud receives write requests when your application issues them. This will allow you to detect and fix data discrepancies as early as possible. This capability is available to Growth plan customers and currently needs to be configured per-environment, so reach out to us on Slack (opens in a new tab) if you'd like us to set it up for you.
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.