|
| 1 | +#Rego authorization policy |
| 2 | + |
| 3 | +##Code style |
| 4 | + |
| 5 | +It's a good idea to consult the[Rego style guide](https://docs.styra.com/opa/rego-style-guide). The "Variables and Data Types" section in particular has some helpful and non-obvious advice in it. |
| 6 | + |
| 7 | +##Debugging |
| 8 | + |
| 9 | +Open Policy Agent provides a CLI and a playground that can be used for evaluating, formatting, testing, and linting policies. |
| 10 | + |
| 11 | +###CLI |
| 12 | + |
| 13 | +Below are some helpful commands you can use for debugging. |
| 14 | + |
| 15 | +For full evaluation, run: |
| 16 | + |
| 17 | +```sh |
| 18 | +opaeval --format=pretty'data.authz.allow' -d policy.rego -i input.json |
| 19 | +``` |
| 20 | + |
| 21 | +For partial evaluation, run: |
| 22 | + |
| 23 | +```sh |
| 24 | +opaeval --partial --format=pretty'data.authz.allow' -d policy.rego \ |
| 25 | +--unknowns input.object.owner --unknowns input.object.org_owner \ |
| 26 | +--unknowns input.object.acl_user_list --unknowns input.object.acl_group_list \ |
| 27 | +-i input.json |
| 28 | +``` |
| 29 | + |
| 30 | +###Playground |
| 31 | + |
| 32 | +Use the[Open Policy Agent Playground](https://play.openpolicyagent.org/) while editing to getting linting, code formatting, and help debugging! |
| 33 | + |
| 34 | +You can use the contents of input.json as a starting point for your own testing input. Paste the contents of policy.rego into the left-hand side of the playground, and the contents of input.json into the "Input" section. Click "Evaluate" and you should see something like the following in the output. |
| 35 | + |
| 36 | +```json |
| 37 | +{ |
| 38 | +"allow":true, |
| 39 | +"check_scope_allow_list":true, |
| 40 | +"org":0, |
| 41 | +"org_member":0, |
| 42 | +"org_memberships": [], |
| 43 | +"permission_allow":true, |
| 44 | +"role_allow":true, |
| 45 | +"scope_allow":true, |
| 46 | +"scope_org":0, |
| 47 | +"scope_org_member":0, |
| 48 | +"scope_site":1, |
| 49 | +"scope_user":0, |
| 50 | +"site":1, |
| 51 | +"user":0 |
| 52 | +} |
| 53 | +``` |
| 54 | + |
| 55 | +##Levels |
| 56 | + |
| 57 | +Permissions are evaluated at four levels: site, user, org, org_member. |
| 58 | + |
| 59 | +For each level, two checks are performed: |
| 60 | +- Do the subject's permissions allow them to perform this action? |
| 61 | +- Does the subject's scope allow them to perform this action? |
| 62 | + |
| 63 | +Each of these checks gets a "vote", which must one of three values: |
| 64 | +- -1 to deny (usually because of a negative permission) |
| 65 | +- 0 to abstain (no matching permission) |
| 66 | +- 1 to allow |
| 67 | + |
| 68 | +If a level abstains, then the decision gets deferred to the next level. When |
| 69 | +there is no "next" level to defer to it is equivalent to being denied. |
| 70 | + |
| 71 | +###Scope |
| 72 | +Additionally, each input has a "scope" that can be thought of as a second set of permissions, where each permission belongs to one of the four levels–exactly the same as role permissions. An action is only allowed if it is allowed by both the subject's permissions_and_ their current scope. This is to allow issuing tokens for a subject that have a subset of the full subjects permissions. |
| 73 | + |
| 74 | +For example, you may have a scope like... |
| 75 | + |
| 76 | +```json |
| 77 | +{ |
| 78 | +"by_org_id": { |
| 79 | +"<org_id>": { |
| 80 | +"member": [{"resource_type":"workspace","action":"*" }] |
| 81 | + } |
| 82 | + } |
| 83 | +} |
| 84 | +``` |
| 85 | + |
| 86 | +...to limit the token to only accessing workspaces owned by the user within a specific org. This provides some assurances for an admin user, that the token can only access intended resources, rather than having full access to everything. |
| 87 | + |
| 88 | +The final policy decision is determined by evaluating each of these checks in their proper precedence order from the`allow` rule. |
| 89 | + |
| 90 | +##Unknown values |
| 91 | + |
| 92 | +This policy is specifically constructed to compress to a set of queries if 'input.object.owner' and 'input.object.org_owner' are unknown. There is no specific set of rules that will guarantee that this policy has this property, however, there are some tricks. We have tests that enforce this property, so any changes that pass the tests will be okay. |
| 93 | + |
| 94 | +Some general rules to follow: |
| 95 | + |
| 96 | +1. Do not use unknown values in any[comprehensions](https://www.openpolicyagent.org/docs/latest/policy-language/#comprehensions) or iterations. |
| 97 | + |
| 98 | +2. Use the unknown values as minimally as possible. |
| 99 | + |
| 100 | +3. Avoid making code branches based on the value of the unknown field. |
| 101 | + |
| 102 | +Unknown values are like a "set" of possible values (which is why rule 1 usually breaks things). |
| 103 | + |
| 104 | +For example, in the org level rules, we calculate the "vote" for all orgs, rather than just the`input.object.org_owner`. This way, if the`org_owner` changes, then we don't need to recompute any votes; we already have it for the changed value. This means we don't need branching, because the end result is just a lookup table. |