How-To Guides
Query Oso Cloud

Query Oso Cloud

Oso Cloud policies are written in the logic programming language Polar. Any time you call Oso Cloud for an authorization decision, Oso 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 Repository

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_road
$ oso-cloud query allow User:john _ Repository:abbey_road
allow(User:john, String:push, Repository:abbey_road)
allow(User:john, String:pull, Repository:abbey_road)

You can also pass multiple variables. This shows all the users and the actions they can do 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 in our policy we have a rule that looks like this.

has_permission(user: User, "push", _: Repository) if

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 for rules other than allow. It is very useful if you want to ask some specific question of your policy that isn't allow or one of the facts you store. For instance, if you wanted to query all the repositories, their parent Organizations and who has the owner role on those parent organizations you could write a custom rule

parent_org_owner(owner: User, org: Organization, repository: Repository) if
    has_relation(repository, "org", org) and
    has_role(user, "owner", org);

We can then query it in different ways. To check a specific repository we could do

$ oso-cloud query parent_org_owner User:_ Organization:_ Repository:abbey_road
parent_org_owner(User:john, Organization:beatles, Repository:abbey_road)

We can also query it to just 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)