Explain
The Explain page gives you insight into your authorize checks. When you use Explain to make an authorization check,
it evaluates all the ways the authorize check could be true. Then for each attempt made, Explain will:
- List all the facts need for the authorization check to succeed
- Highlight the rules from your policy that apply to the authorization check
For successful attempts, Explain also shows the facts from your Oso Cloud environment that support the authorization decision.
Explain page layout
There are 5 key areas to the Explain page as numbered in the image below.
1. Run authorization checks
This section allows you to run any authorize check that is supported by your current policy. Enter an actor,
action, and resource and click the "Run" button. The Explain page will populate results based on the authorization
check you make here. The image shows an example authorizecheck which asks: Does User:paula have the "admin_view"
permission on Organization:org_1?
2. Authorization attempts
This section allows you to select authorization attempts. An attempt explains one way (out of possibly many) an authorization check can succeed. Use the arrows (or click on a tab) to select an attempt.
- A green check mark and the word "Pass" indicates that the authorization check succeeded during that attempt.
- A red x and the word "Fail" indicates that the authorization check did not succeed during that
attempt.
NOTE: Multiple successful attempts can exist. However, only one successful attempt is needed for an authorization check to pass.
3. The condition for the attempt to succeed
This section of the page lists the facts that are needed for an authorization check to succeed in the given attempt. Each attempt presents a unique set of facts. It does not necessarily represent the facts that are currently in your environment.
4. The matching facts currently existing in your environment
This section shows the facts currently in your environment that support successful authorization attempts. If an authorization attempt fails, nothing will be shown in this section.
5. The part of your policy that is evaluated when the authorization check is made
This section shows the rule within your policy that enforces the authorization check for the selected attempt.
Next Steps
Read on to see how to use the logs and the explain tool together to debug an unexpected authorization result
Talk to an Oso engineer
If you have any questions about this guide, or you're still stuck on an authorization check after using Explain, schedule a 1x1 with an Oso engineer. We're happy to help.