Local Authorization

Oso can make decisions based on data stored in your own database, which is known as local authorization. In these cases, Oso never needs to read the data, only understand its structure.

How local authorization affects authorization decisions

When Oso receives an authorization request, it evaluates the policy to aggregate sets of facts (typically represented in authorization data) which, if true, let the request succeed.

When using one of Oso's distributed check APIs (which rely on local authorization), the Oso client returns a SQL expression which you can use to perform the authorization decision locally. Depending on which type of authorization you're performing, the expression can either be a whole query or a fragment that you use inside another query.

Note that centralized authorization data still affects local authorization decisions.

When to use local authorization

You should leave data in your application database if its primary purpose is to support application functionality. Examples include data that:

• Only affects authorization for a single service, e.g. the owner of an issue
• Changes frequently, e.g. CI job IDs
• Has high cardinality, e.g. files in a large catalog

For an account of when to use local authorization versus other strategies, see Authorization data.

Local authorization overview

To use local authorization, at a high level:

1. Configure how facts in your policy correlate to tables in your database.
2. Call the distributed check API in your application's authorization enforcement code. This API returns a SQL expression––either a full query or a fragment to use in another query's WHERE clause.
3. Use the returned SQL fragment when querying the database storing the data that affects authorization.

For a more thorough description of using local authorization, see the guide on filtering lists with decentralized data.

Configure fact representation

When Oso evaluates authorization requests based on your policy, it aggregates sets of facts which, if true, mean the request succeeds.

In the context of local authorization, this means that Oso needs to understand how to translate facts (e.g. has_role(User{"alice"}, "admin", Organization{"acme"})) into expressions your database can evaluate.

You'll describe this translation from fact to SQL query with a YAML configuration file, structured like so:

facts

The facts section is required and is where the majority of your configuration logic lives. It consists of one key for each fact signature stored in your database. Fact signatures are specified with a predicate (e.g. has_role, has_relation etc.) followed by a parenthesized list of comma-separated arguments (e.g. User:_, String:admin etc.).

Each fact signature must have a query value, which specifies the SQL query that will be used to look up facts matching this signature.

The _ symbol in a fact signature indicates that the <id> of the entity is a variable returned by the query. For example, the signature

says: "this SQL query returns one row for every Issue that has a parent Repository".

The query value for a signature must return the same number of columns as there are wildcards in the signature. This means that for the signature above, this

is invalid. A valid query would be

Additional Restrictions

• Fact signatures must be used by rules in your policy (they wouldn't do much if they didn't).

• Fact signatures also must not "overlap", meaning they must all be mutually exclusive. Consider this example:

  
  

  facts:

  is_protected (Repository:_, Boolean:true):

  query: |-

  select id

  from repository

  where is_protected

  is_protected (Repository:_, Boolean:false):

  query: |-

  select id

  from repository

  where !is_protected

  
  

  These facts don't overlap, so this is valid! On the other hand:

  
  

  facts:

  is_protected (Repository:_, Boolean:_):

  query: |-

  select id, is_protected

  from repository

  is_protected (Repository:_, Boolean:false):

  query: |-

  select id

  from repository

  where !is_protected

  
  

  These facts do overlap. Slightly more formally the set of facts matching the signature is_protected (Repository:_, Boolean:_) contains the set of facts matching the signature is_protected (Repository:_, Boolean:false).

• Each query must be a SELECT statement (Technically a <query specification> per SQl-92 (opens in a new tab)). Common table expressions (CTEs), subqueries, and set expressions like UNION are allowed, but each of these must also be a SELECT. The following is not valid, because the CTE is an UPDATE statement:

  
  

  WITH inserted as (

  UPDATE issue

  SET parent_repo = 1

  RETURNING id, parent_repo

  )

  SELECT id, parent_repo

  FROM inserted

  
  

sql_types

sql_types maps resources in Oso Cloud (e.g. Issue, Repository) to their data types in your application database. This allows authorization queries returned by the distributed check API to more effectively use indexes, improving query performance.

The sql_types section is optional, but strongly recommended.

Example

This example tells Oso that has_relation facts that associate issues with their parent repositories can be resolved by running a query (SELECT id, repository FROM issues) against your application's database.

Validate data bindings

You can check that the YAML configuration describes valid bindings using the oso-cloud CLI.

Guides

• List filtering

Distributed Check API

After configuring local authorization for your application, the distributed check API allows you to perform authorization using data that's distributed across Oso Cloud and your own database.

The methods are documented under the appropriate Client SDK:

• CLI
• Node
• Python
• Go
• Java
• Ruby
• .NET

Note that centralized authorization data still affects local authorization decisions.

Limitations

Oso Local Authorization currently has the following limitations:

• Only supports PostgreSQL. The minimum tested version is PostgreSQL 14.10.
• Does not support:
  • Context facts
  • Recursive logic involving data in your database
  • Logic that may allow all resources depending on data in your database
  • Inequality comparisons between data stored in Oso Cloud and data stored in your database

Related content

• For a comprehensive example of local authorization, see Ruby on Rails list filtering sample app (opens in a new tab)
• Facts: The Oso Cloud data model