Oso Cloud's Explain helps you understand the reasoning behind authorization decisions. Given an authorization question like "Can User:alice perform the read action on Repository:anvil?", Explain shows you the ways the answer could be true, based on your policy. Explain also shows you the facts that back up these answers.

Explain is useful for debugging if you get an authorization result you don't expect or understand. You can also use it to visualize the way your policy and facts interact.

Using Explain

To use Explain, enter the actor, action, and resource you want to authorize. Write these in terms of types and IDs, using the same format as the authorize CLI command. For example, to get an explanation for the authorization question from above, enter User:alice "read" Repository:anvil. Next, click "Run".

On the left, the "Attempts" column shows the various ways that this authorization query could be allowed based on your policy. Some attempts succeed and some attempts fail— attempts that succeed have the facts to back them up. If any single attempt succeeds, the authorization query is allowed. If none of the attempts succeed, the authorization query is denied. Click on an attempt to see more detail.

In the center, you can see the explanation for the selected attempt. Each attempt requires a certain set of facts to succeed. For example, the first attempt for User:alice "read" Repository:anvil requires the fact has_role(User:alice, "reader", Repository:anvil). If you have inserted every required fact into Oso Cloud for an attempt, the attempt succeeds, and the authorization query is allowed.

Some attempts may require multiple facts related by intermediate variables. For example, the second attempt for User:alice "read" Repository:anvil requires both has_relation(Repository:anvil , "organization", related_organization) and has_role(User:alice, "member", related_organization), where related_organization is a variable.

For successful attempts like these, Explain shows the bindings for the intermediate variables. In this case, the variable related_organization is bound to the concrete value Organization:acme_corp.

On the right, Explain shows your policy, so you can cross-reference explanations with lines in your policy. When you're debugging, this can help you understand whether there's a problem in your policy or in the set of facts you've inserted.