Context Facts

Context facts let you provide additional, request-specific facts alongside an authorization decision. These facts are considered true only for the duration of that decision and are not stored persistently. Common examples include a user’s geographic location or local time at the moment of the request.

How context facts affect authorization

When Oso evaluates an authorization request, it checks the policy against known facts (typically stored in Oso Cloud); if the facts are true, the request succeeds. Context facts can also satisfy policy conditions, letting you provide information that exists only at request time. If a context fact isn’t provided, Oso checks the centralized fact storage instead.

Example

Consider a policy rule:

has_permission(user: User, "delete", account: Account) if
  has_relation(user, "owner", account) and
  request_came_from_eu(true)

You may not want request_came_from_eu to be globally true. Instead, provide it as a context fact when appropriate:

oso.js

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"},
  "delete",
  {type: "Account", id: "alice"},
  [ // Context Facts
    ["request_came_from_eu", {type: "Boolean", id: "true"}]
  ]
);

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

oso.py

import os

from oso_cloud import Oso
from oso_cloud import Value

oso = Oso(api_key=os.environ.get('OSO_CLOUD_API_KEY', None))

actor_value = Value("User", "alice")
resource_value = Value("Account", "alice")

authorized = oso.authorize(
    actor_value,
    "delete",
    resource_value,
    [ # Context Facts
        ("request_came_from_eu", Value("Boolean", "true"))
    ]
)

print(f"Authorization result is {authorized}")

oso.go

package main

import (
  "os"
  "fmt"
  oso "github.com/osohq/go-oso-cloud/v2"
)

func main() {
    apiKey := os.Getenv("OSO_CLOUD_API_KEY")

    osoClient := oso.NewClient("https://cloud.osohq.com", apiKey)

    authorized, err := osoClient.AuthorizeWithContext(
        oso.NewValue("User", "alice"),
        "delete",
        oso.NewValue("Account", "alice"),
    []oso.Fact{ // Context Facts
        oso.NewFact(
            "request_came_from_eu",
            oso.NewValue("Boolean", "true"),
        ),
    },
    )

    if err != nil {
        fmt.Printf("Error during authorization: %v", err)
    }

    fmt.Printf("Authorization result was %v", authorized);
}

oso.rb

require 'oso-cloud'

api_key = ENV.fetch('OSO_CLOUD_API_KEY', nil)

oso = OsoCloud::Oso.new(url: "https://cloud.osohq.com", api_key: api_key)

authorized = oso.authorize(
  OsoCloud::Value.new(type: "User", id: "alice"),
  "delete",
  OsoCloud::Value.new(type: "Account", id: "alice"),
  [ # Context Facts
    ["request_came_from_eu", OsoCloud::Value.new(type: "Boolean", id: "true")]
  ]
)

puts "Authorization result was #{authorized}."

Oso.cs

using OsoCloud;

string? apiKey = Environment.GetEnvironmentVariable("OSO_CLOUD_API_KEY");

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

var authorized = await oso.Authorize(
  new Value("User", "alice"),
  "delete",
  new Value("Account", "alice"),
  new List<Fact> { // Context Facts
    new Fact("request_came_from_eu", new List<Value> {
        new Value("Boolean", "true")
    })
  }
);

Console.WriteLine("Authorization result was " + authorized);

Oso.java

package com.mycompany;

import java.io.IOException;

import com.osohq.oso_cloud.Oso;
import com.osohq.oso_cloud.api.ApiException;
import com.osohq.oso_cloud.api.Value;

public class App 
{
    public static void main( String[] args )
    {
        String apiKey = System.getenv("OSO_CLOUD_API_KEY");

        Oso oso = new Oso(apiKey);

        Value actor_value = new Value("User", "alice");
        Value resource_value = new Value("Account", "alice");

        try
        {
            boolean authorized = oso.authorize(
              actor_value,
              "delete",
              resource_value
            );
            
            System.out.println("Authorization result was " + authorized);
        }
        catch (IOException e)
        {
           System.err.println("Error communicating with Oso Cloud: " + e.getMessage());
        }
        catch (ApiException e)
        {
           System.err.println("API error communicating with Oso Cloud: " + e.getMessage());
        }
    }
}

terminal

oso-cloud authorize User:alice delete Account:alice \
  -c "request_came_from_eu Boolean:true"

When to use context facts

Use context facts when authorization depends on ephemeral or external data that isn’t part of your database. Examples:

Identity provider (IDP) claims: Roles or permissions that exist only on a user’s authentication token (e.g. is_admin(user) from a JWT). Context facts let you pass these values without syncing them to Oso Cloud.
Request-specific properties: Information like IP address, time of day, or location: is_weekend(true) or request_came_from_eu(true)).

In most other contexts, we recommend using Local Authorization. See Data management for how context facts compare to other strategies.

Using context facts with the Check API

All SDKs support including context facts in check calls. The methods are documented under Authorization Checks. Some SDKs also let you include context facts with the local check API. See Local Authorization for more information.

Get Started

Develop

Deploy and Manage

How context facts affect authorization

Example

When to use context facts

Using context facts with the Check API

Get Started

Develop

Deploy and Manage

Documentation Index

​How context facts affect authorization

​Example

​When to use context facts

​Using context facts with the Check API

How context facts affect authorization

Example

When to use context facts

Using context facts with the Check API