Authorize requests

Oso's primary purpose is to provide authorization for your application, such as ensuring actors have specific permissions on resources before reading or writing data.

Authorization is composed of two parts:

  • Decisions, where Oso uses your policy to evaluate some authorization data to determine some outcome––for example, allowing or denying a request.
  • Enforcement, where your application takes action based on Oso's decision.

Said another way:


authorization = decision + enforcement

This document focuses on authorization decisions. We also have a document on enforcement.

Decision APIs

Oso provides the following built-in decision APIs:

Decision APIDescription
Explicit authorizationWhether a user has a permission on a resource
List of user's resources with permissionA list of resources a user has a permission on
List of user's permissions on a resourceA list of permissions a user has on a resource

A few important notes:

  • Each mechanism has multiple implementations, based on whether or not you are using local authorization (retaining any authorization data locally) or solely using centralized authorization (where all authorization data is synced to Oso Cloud).

    Note that if you are using local authorization whatsoever, you should use that version of the API––any authorization data you centralized in Oso Cloud still affects your local authorization queries.

  • You can also query Oso Cloud for facts it can infer and make authorization decisions yourself.

Explicit authorization

The most common authorization pattern is determining if a specific user has a specific permission on a specific resource. In this case, you can use Oso's authorize API.

SDKLocal authCentralized auth only
CLIauthorize-localauthorize
NodeauthorizeLocalauthorize
Pythonauthorize_localauthorize
GoAuthorizeLocalAuthorize
JavaauthorizeLocalauthorize
Rubyauthorize_localauthorize
.NETAuthorizeLocalAuthorize

Details

Internally, Oso Cloud clients converts the above commands into queries using the allow predicate.

To support this, all Polar policies have a default allow rule, which you may override with a custom allow rule. For more information, see Polar rules and facts: Default & custom allow rules.

List of user's resources with permission

You might want to get a list of resources that users have a specific permission on, for instance all of the resource IDs a user can read. In this case, use the list API.

SDKLocal authCentralized auth only
CLIlist-locallist
NodelistLocallist
Pythonlist_locallist
GoListLocalList
JavalistLocallist
Rubylist_locallist
.NETListLocalList

For more detail about using the list API with local authorization, see List filtering.

Details

Internally, Oso Cloud clients converts the above commands into queries using the has_permission predicate.

List of user's permissions on a resource

You might want to get a list of permissions a user has on a specific resource, such as all of the things a user can do to a blog post. In this case, use the actions API.

SDKLocal authCentralized auth only
CLIunimplementedactions
NodeactionsLocalactions
Pythonactions_localactions
GoActionLocalActions
JavaactionsLocalactions
Rubyactions_localactions
.NETActionsLocalActions

Details

Internally, Oso Cloud clients converts the above commands into queries using the has_permission predicate.

Other resources

For more details about...