Quickstart

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

Before we get started

You'll need a couple of things for this tutorial:

An Oso Cloud account. You can get one at https://ui.osohq.com (opens in a new tab).
A sample application that you can modify and launch locally. We have clients for Node, Python, Go, Ruby, and .NET.

Building 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.

Use the Rules Workbench (opens in a new tab) to add a resource, a type of thing which may be accessed. For example, you may add a resource named Repository to control how users access repositories in a multi-tenant application. You will get a policy that looks like this:


actor User {}
resource Repository {
  roles = ["viewer", "owner"];
  permissions = ["view", "edit"];
  "view" if "viewer";
  "edit" if "owner";
  "viewer" if "owner";
}

The Rules Workbench automatically added some common roles and permissions. It has also defined an actor, a type of thing which may access resources.

💡

We will use this example for the remainder of the guide, but feel free to customize your policy further.

Now that you've built a policy, deploy it with the button 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.

Adding Oso Cloud to your application

You're ready to add Oso Cloud to your application, so load up the application code in your favorite IDE.

Generate a new read-write token from the Settings (opens in a new tab) page and initialize your environment.
Follow the steps on the Install (opens in a new tab) page to integrate Oso Cloud into your application. The sample code uses hardcoded values for the Actor and Resource IDs. In practice, you'll retrieve these from contexts available to your application; the hardcoded values are good enough for now, and we'll use them in our examples.

Launch your application and attempt to access the endpoint now protected by Oso Cloud. You'll get an exception. That's because you still need to grant the permission to the Actor! You can see information about this denied request on the Logs (opens in a new tab) page.

Granting permissions

You grant permissions by adding facts. Facts are the authorization-relevant data that Oso Cloud will use to determine access.

Following our example, if we want to allow User{"123"} to "view" Repository{"456"}, we need to add the following fact:


has_role(User{"123"}, "viewer", Repository{"456"})

You can do this using the Data (opens in a new tab) page.

Now, try reaccessing the endpoint. No exceptions!

🎉

Congratulations, you've successfully added enforcement to your application.

Continuing the journey

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 →

Authorization Modeling