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:
Type | Id |
---|---|
"User" | "5480174f-3f42-4a91-845c-c913530ca2c9" |
"Guest" | "11235813" |
"Admin" | "alice@example.com" |
"Machine" | "foo-service-identifier-01" |
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.).
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:
Type | Id |
---|---|
"File" | "5480174f-3f42-4a91-845c-c913530ca2c9" |
"Organization" | "acme-corp" |
"Profile" | "alice@example.com" |
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:
resource Organization { roles = ["member", "owner"]; permissions = ["view", "invite"]; "view" if "member"; "invite" if "owner"; "member" if "owner";}
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:
allow(actor, action, resource) if conditions;
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.