Query Oso Cloud
Oso Cloud policies are written in the logic programming language Polar.
When you create a policy and call Oso Cloud for an authorization decision, Oso Cloud queries that policy.
For example, one endpoint is list, which returns a list of the resources a User
can do an action on.
Making a list call with the CLI looks like this:
$ oso-cloud list User:john push Repositoryabbey_road
What list is doing is querying for the allow rule. The allow rule can be
written directly or is generated automatically if you are using Resource Blocks.
The query equivalent to list would look like this.
$ oso-cloud query allow User:john push Repository:_allow(User:john, String:push, Repository:abbey_road)
The way query works is that you pass a rule name and arguments and it returns a list of facts that match that rule. These facts can be derived by a polar rule like allow.
A variable, also known as a wildcard is a way to match anything for that argument.
Polar will return all the possible rule definitions that match. A variable can have
a type like Repository:_ or it can be a typeless variable _.
Variables can be used for any argument. Passing a variable for the action instead of
the resource would be equivalent to the actions method.
$ oso-cloud actions User:john Repository:abbey_roadpushpull$ oso-cloud query allow User:john _ Repository:abbey_roadallow(User:john, String:push, Repository:abbey_road)allow(User:john, String:pull, Repository:abbey_road)
Pass multiple variables to show all the users and the actions they can perform on repositories:
$ oso-cloud query allow _ _ Respository:_allow(User:sam, String:push, Repository:_)allow(User:john, String:push, Repository:abbey_road)allow(User:john, String:pull, Repository:abbey_road)allow(User:ringo, String:push, Repository:abbey_road)allow(User:ringo, String:pull, Repository:abbey_road)allow(User:payl, String:pull, Repository:abbey_road)allow(User:sully, String:push, Repository:paperwork)...
Notice that the first result there included a variable for the resource. That is because the policy has a rule that looks like this:
has_permission(user: User, "push", _: Repository) if super_admin(user);
User:sam is a super_admin which means he can push to any Repository. This variable
does not get tied to any specific Repository when it's queried so is returned as a
variable.
Querying Custom Rules
Query can also be used to search for things besides allow rules or stored facts. This is useful when you want to ask specific questions about your policy.
For instance, suppose you wanted to query:
- All the repositories,
- The parent organizations of those repositories, and
- Who has the role of
owneron the parent organizations
First, add a custom rule to your policy:
parent_org_owner(owner: User, org: Organization, repository: Repository) if has_relation(repository, "org", org) and has_role(user, "owner", org);
You can then query it in different ways. Check for a specific repository using the following query:
$ oso-cloud query parent_org_owner User:_ Organization:_ Repository:abbey_roadparent_org_owner(User:john, Organization:beatles, Repository:abbey_road)
Or, list all the repositories and their organization owners.
$ oso-cloud query parent_org_owner User:_ Organization:_ Repository:_parent_org_owner(User:john, Organization:beatles, Repository:abbey_road)parent_org_owner(User:mike, Organization:monsters, Repository:paperwork)...
Talk to an Oso Engineer
If you'd like to learn more about using Oso Cloud in your app or have any questions about this guide, schedule a 1x1 with an Oso engineer. We're happy to help.