Reference
Local Authorization

Local Authorization

In Oso, you can make authorization decisions using data stored in Oso Cloud, as well as data stored in your own database.

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 SQL fragments appropriate to use as the contents of a WHERE clause elsewhere.
  3. Use the distributed check API's SQL fragment as the WHERE clause in the query accessing the resource. Only resources the requestor should have access to, according to your policy, will be returned.

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:


# One entry per fact signature in your database
facts:
# Ex:
# has_relation(Issue:_, parent, Repository:_):
<predicate> ([<type>:]{_, <id>} )*:
# Ex:
# query: SELECT id, repository FROM issues
query: <sql_query>
# Optional map of resource <type>s to their data type in your application database
sql_types:
# Ex:
# Issue: UUID
<type>: <sql_data_type>

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


has_relation(Issue:_, String:parent, Repository:_):

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


SELECT issue.id, 'parent', issue.parent_repo
FROM issue

is invalid. A valid query would be


SELECT issue.id, issue.parent_repo
FROM issue

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


facts:
has_relation(Issue:_, parent, Repository:_):
query: SELECT id, repository FROM issues
sql_types:
Issue: UUID
Repository: UUID

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.

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:

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

Up next

Glossary