Glossary

Oso Cloud is an authorization system; its purpose is to allow you to selectively control access to certain application resources. In this document, we’ll explore the basic concepts that Oso Cloud uses to help you accomplish this goal.

Actions

Actions are the verbs of authorization queries. They distinguish between different kinds of queries for a given resource by indicating what the actor is attempting to do. For a web application, the action might be an HTTP request method like GET or POST.

In Oso Cloud, actions are strings. For example: "view", "create", "PATCH", etc.

Actors

Actors are the subjects of authorization queries. Actors will often be application end-users, but could also represent service users, API clients, or other internal systems. They may be represented by simple strings such as usernames or email addresses, or by a structured identity token like a JWT.

In Oso Cloud, actors are identified by a pair of strings: Type & ID. For example:

Facts

Oso Cloud represents data as facts. Facts are a flexible data model for representing any authorization-relevant data in an application.

They consist of a name and arguments. Each argument either references a resource in the application (by its type and identifier), or a literal value, such as a string.

Facts are provided for authorization in one of two ways:

• Storing them in Oso Cloud using the tell API, or
• Sending Context Facts along with Check API calls.

Context Facts

Context facts are a type of fact that is not stored in Oso Cloud. Context facts only affect the API call they're sent with, and they do not persist across requests. Any number of context facts can be sent with a request to a Check API (authorize, query, list, etc.).

For more details, see Context Facts.

Policies

Oso evaluates queries using authorization logic contained in policies. Policies are written as code in a configuration language called Polar. Polar is designed to provide a simple but expressive syntax for authorization logic.

Policies are stored in Polar files (with the .polar extension) and uploaded to Oso Cloud using the CLI. Once loaded, policies are used to evaluate authorization queries.

Policies are made up of resource blocks and rules.

Queries

In Oso Cloud, an authorization query takes the form:

May actor perform action on resource?

Queries are made using the Check API.

Resources

Resources are the objects of authorization queries. They represent the application components that we wish to protect.

In Oso Cloud, resources are identified by a pair of strings: Type & ID. For example:

Resource Blocks

Resource blocks are shorthand syntax for grouping authorization logic pertaining to a particular type of resource. Consider the following resource block for the Organization type:

The above resource block declares that actors can have two different roles on an organization, "member" and "owner"; that members are allowed to "view" the organization and owners allowed to "invite" to it; and that owners are allowed to do anything that members are allowed to do.

Rules

The other policy building block is a rule. A rule is a statement that can evaluate to true or false. In Oso Cloud, one such rule is distinguished and used to drive the authorization decision: the allow rule.

A basic allow rule has the form:

We can read this as:

actor may perform action on resource if conditions hold

When we make an authorization query via one of the Check API methods, Oso Cloud decides whether the query is allowed or denied by matching the supplied actor, action, and resource arguments with the parameters of allow rules specified in the policy.

Summary

• In Oso, authorization begins with a query, which is evaluated against a policy written in the Polar language.
• Policies are made up of resource blocks and rules, and allow rules are the entrypoint for queries made via the Check API.

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, connect with us on Slack. We're happy to help.

Get started with Oso Cloud →