Quickstart

Welcome to Oso! Let's get you started on the journey to supercharge authorization in your application.

⛳ Quick hands-on

If you like learning by doing, jump into Oso by playing a round of Oso golf (opens in a new tab) (inspired by Regex golf).

Get started with Oso

To get started, you'll need an Oso Cloud account. You can get one at https://ui.osohq.com (opens in a new tab).

Build your first policy

The first thing you need on this journey is a policy. A policy contains the authorization logic that Oso Cloud will use to determine access.

Authorization logic is made up of two pieces:

Resources describing the "who" and "what" of your application. The "who" are identified as actors, while the "what" are resources.
Rules describing the authorization logic, usually in terms of actors and resources.

Open the Rules Workbench (opens in a new tab) to add a policy defining resources and rules:


# Who will be performing actions in our application.
actor User {}
# What will actors be acting upon.
resource Organization {}
# A rule stating that users have permission to edit an organization
# if they have the admin role on that organization.
has_permission(user: User, "edit", organization: Organization) if
    has_role(user, "admin", organization);

Now that you've built a policy, we can make it accessible by clicking Deploy in the upper-right of the Rules Workbench. That's it!

In practice, your policy will have some more bells and whistles. We'll add those in due time, but this is enough to get things rolling.

Add data to support the policy

With a policy in place, you now need to provide data in the form of facts. Facts are the authorization-relevant data that Oso Cloud will use to determine access.

Let's first see what Oso does without any data present, then add the data and perform the same action.

Query your policy without data

First, try to perform an authorization request asking if the user Alice can edit the Acme organization.

Go to Oso Cloud's Explain tab (opens in a new tab), which lets you run authorization queries from the UI.
In the Authorize field, enter:
User:alice edit Organization:acme
Click Run.

You don't need to be too concerned with the details, but you should see that all of the Attempts have a Fail output.

This authorization request fails because Oso has no idea who Alice is or her relationship to the Acme organization.

Add authorization data

When you ask Oso to make authorization decisions, it evaluates the request in context of your account's policy (which we deployed above), as well as the set of facts you've made available (which we haven't done yet). For instance, identifying a given user's role in an organization is a common type of fact you'd send to Oso.

While you will typically manage your data in other ways, you can add facts in the Oso Cloud UI.

Because the last authorization query we tried failed (which is a good thing!), you should tell Oso that Alice is an admin at Acme.

Go to Oso Cloud's Data tab (opens in a new tab)
Next to the fact type has_role (User, "admin", Organization), click Add.
Fill out the fact fields:
Field Value
User alice
Organization acme
Click Add this fact.

Field	Value
User	alice
Organization	acme

Authorize requests using your policy + data

Now that we've added the appropriate authorization data, let's evaluate the same authorization request we made earlier asking if Alice can edit the Acme organization. You should expect the request to succeed because Alice is an admin at Acme, and admins can edit organizations based on the rules in our policy.

Go to Oso Cloud's Explain tab (opens in a new tab), which lets you run authorization queries from the UI.
In the Authorize field, enter:
User:alice edit Organization:acme
Click Run.

Now, in the Attempts column, you should see at least one Pass value.

You've already seen that Oso will deny any other authorization requests, but feel free to convince yourself with any other requests that interest you.

Continue the journey

You've gotten a very small sample of how Oso works: you describe a policy, and then can make authorization decisions based on that policy and facts about your actors and resources.

Get more hands-on experience by playing a round of Oso golf ⛳ (opens in a new tab)
Learn more about writing policies in our Intro to Polar
Learn the steps for building authorization with Oso Cloud

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 →

Intro to Polar