Quickstart

Hey there!

Welcome to Oso - we are delighted you are here.

Let’s explore how to use Oso’s authorization as a service platform for the first time.

In this quickstart, you will learn:

• How Oso works
• How to understand your first policy
• How to add user and role data
• How to authorize your first user in the Workbench console
• How to get your free API key
• How to install an Oso software development kit (SDK) for your go-to programming language
• How to authorize your first user with your own code.

Once we are complete, we'll be able to authorize using Oso in your own code like this:

import { Oso } from 'oso-cloud'

const apiKey = process.env.OSO_CLOUD_API_KEY;

const oso = new Oso("https://cloud.osohq.com", apiKey);

const authorized = await oso.authorize(
  {type: "User", id: "Alice"},
  "view",
  {type: "Item", id: "foo"}
);

console.log("Authorization result was " + authorized);

Let’s get started!

Sign up for Oso Cloud

First, we need to sign-up for an Oso developer account. The developer tier is free for teams of up to 5 developers and 100 monthly active users.

To sign up for Oso Cloud, click here (opens in a new tab).

How Oso works

Building authorization with Oso Cloud requires two components:

1. An authorization policy
2. User data

An authorization policy is defined using Oso’s domain specific language Polar (opens in a new tab). It is a simple, expressive representation of the authorization rules in your application. A policy written in Polar can be defined using .polar files or Oso’s Workbench console.

User data are defined in Oso as Facts (opens in a new tab). While we define the authorization permissions in Oso with policies, we define the current state of users and resources by storing Facts in Oso. You can add Facts in Oso using your own code or - to get started - Oso’s Workbench console.

With these two main concepts - authorization policies and user data - in mind, let’s create the first component we need: our first policy.

Create your first policy

Let’s get started creating our first policy. Navigate to the Rules Editor and switch to Workbench mode.

To explore the Workbench, click here (opens in a new tab).

Since the Rules Editor is empty, let’s start by creating a resource. To keep it simple, we use a generic example: Item.

Resources can be any data object in your application you wish to secure with authorization. Documents, contacts, files and images are Resources frequently defined in Oso.

Click the input box next to Add a resource , input “Item” and click the + icon.

We now have a policy with two primitive building blocks - an Actor and a Resource . A User is an Actor seeking authorization to access a Resource— in our example, an Item.

With this policy, we can see a User can have two roles on an Item :

1. viewer
2. owner

By default, an Item has two roles: a viewer and an owner. A User who is a viewer of an Item cannot edit. A User who is an owner of an Item can edit. In the future, we can customize roles and permissions to our application’s needs.

A User with the owner role can both view and edit an Item.

With these roles defined on our resource Item, we can deploy this policy to Oso.

To deploy our first policy, click the button Deploy in the top right.

We now have a usable policy.

To use our policy, next we add user and role data as Facts in Oso.

Add user and role data

We store our user and role data in Oso as Facts. Facts are a flexible data model for representing the authorization data from your application.

To start, we create two Facts. These two Facts create two Users with two different roles.

1. Alice
2. Bob

We assign Alice the role owner on an Item we call “foo.” We assign Bob the role viewer on an Item we call “foo.”

We can use the Data tab in the Oso console to add these users and roles as Facts.

To add these Facts using the Oso console, click here. (opens in a new tab)

Inside the interface, we can see the type of Fact we want to create: has_role.

Let’s add Alice as an owner of an Item by assigning the has_role Fact.

To add Alice as an owner of an Item , first click Add next to has_role ( Actor, "owner", Item ).

Next, input “Alice” as the User ID.

Then, input “foo” as the item.

Finally, to save our first Fact assigning Alice as an owner of the Item called “foo,” click Add this fact.

Great! We have our first Fact created. Next, we use the same method to add Bob as a viewer for the Item "foo."

To add Bob as a viewer of Item , first click Add next to has_role ( Actor, "viewer", Item ).

Next, input “Bob” as the User ID.

Then, input “foo” as the item.

Finally, to save our first Fact assigning Bob as an viewer of an Item called “foo”, click Add this fact.

Awesome! We have the two components we need to authorize users in Oso:

1. Our first policy
2. Our first facts

Next, we test both our policy and our facts by authorizing Alice and Bob in the Oso console.

Authorize your first user

Now we can authorize our first user. We can do that in the Oso console by navigating to Explain.

To authorize our first user, click on Explain (opens in a new tab) in the Oso console.

First, we test if Alice can view an Item named “foo.”

To test if Alice can view an Item named “foo”, input User:Alice view Item:foo in the Authorize field. Then click Run.

Install an Oso Software Development Kit (SDK)

Excellent! With our tested policy and Facts, we authorize a user in our application’s code.

First, we install an Oso SDK. Oso publishes SDKs in many popular programming languages to make authorization easier and idiomatic.

To install an Oso SDK, select your programming language of choice and input the terminal command.

npm install oso-cloud

Get your free API key

Nice! With our Oso SDK installed, we next need to get an Oso API key. This secret authenticates the Oso client in our code with Oso Cloud.

To get our free API key from the console, click here (opens in a new tab).

As we are using Oso for the first time, we create a development key.

To create a new development API key, click Create development API key.

In the Name field, we input "Test".

For our testing purposes, we make this a Read-Only key by clicking Read-Only.

To create our development API key, we click Create.

Then, we copy the API key to our clipboard by clicking Copy.

Note: we cannot see this API key again. Store it in a secure location.

With our API key stored and exposed securely to our application, we are ready to authorize our first user.

Authorize your first user with code

With our Oso SDK installed and API key exposed to our application, we can authorize our first user. In many languages, this can be achieved in just a few lines of code.

First, we import our Oso SDK.

Then we instantiate an Oso client using our API key.

Next, create a value for the user named Alice.

Next, we create the Value of our resource, starting with an Item named foo.

Finally, we authorize our actor_value for the permission edit with our resource_value.

import { Oso } from 'oso-cloud'

const apiKey = process.env.OSO_CLOUD_API_KEY;

const oso = new Oso("https://cloud.osohq.com", apiKey);

const authorized = await oso.authorize(
  {type: "User", id: "Alice"},
  "edit",
  {type: "Item", id: "foo"}
);

console.log("Authorization result was " + authorized);

If our authorization is successful, we should see the result be True.

Let’s see if we can do the same for our User Bob.

First, we change our actor_value to the User Bob.

Then we authorize actor_value for the permission edit with our previously defined resource_value.

import { Oso } from 'oso-cloud'

const apiKey = process.env.OSO_CLOUD_API_KEY;

const oso = new Oso("https://cloud.osohq.com", apiKey);

const authorized = await oso.authorize(
  {type: "User", id: "Bob"},
  "edit",
  {type: "Item", id: "foo"}
);

console.log("Authorization result was " + authorized);

If our authorization is unsuccessful - as Bob is a viewer - we should see the result be False.

What’s next

Congratulations! We completed our first authorization with Oso.

We’re excited that you’re here and can’t wait to learn more about what you are building.

Continue your journey with Oso by learning more about policies, Facts and best practices for authorization.

• Dive into modeling your policy with Polar (opens in a new tab).
• Find out how to make authorization decisions based on data stored in your application's database (opens in a new tab).
• Learn how to sync your user and role data in production (opens in a new tab).
• Learn more about this problem domain with our Authorization Academy (opens in a new tab).
• Why not play a round of Oso golf (opens in a new tab)?.

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 →