Context Facts
Oso lets you provide additional facts along with each authorization decision, which lets Polar consider those facts to be true only for this decision and only for the lifetime of the decision. For example, you might want to use context facts to describe the user's geographic locale or their local time.
How context facts affect 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.
Any facts included as context facts can meet this requirement, letting the request succeed. For example, this means that you can provide data that is only available from a user's environment when making authorization decisions, without worrying about the user's state changing.
If Oso cannot find the authorization data provided as a context fact, it still consults the centralized fact storage.
Example
Consider a rule like this in a policy:
has_permission(user: User, "delete", account: Account) if has_relation(user, "owner", account) and request_came_from_eu(true)
If you have an international customer base, you would not want to state that
request_came_from_eu is unconditionally true. However, you could provide this
as a context fact in cases where it's appropriate. For example:
oso-cloud authorize User:alice delete Account:alice \
-c "request_came_from_eu Boolean:true"When to use context facts
You may have data that isn't stored in your database, but still affects authorization. You can incorporate this data by using context facts, which exist only for the duration of a request.
Situations where context facts make sense include:
- Information from an external source, like an identity provider (IDP). In
your system there may be roles or permissions that exist solely on a user's
authentication token from an identity provider (such as a JWT) — in these
cases, you can pass that extra information using context facts
like
is_admin(user). This lets you avoid synchronizing your IDP information with Oso Cloud. - Request-specific context: if you want to protect resources based on
ephemeral request properties like IP addresses or time of day, you can pass
them as context facts such as
is_weekend(true)orrequest_came_from_eu(true).
In most other contexts, we recommend using Local Authorization.
For details about context facts versus other strategies, see Authorization data.
Check API
Oso's check API lets you include context facts alongside your checks. The methods are documented under the appropriate Client SDK:
In some SDKs, you can also include context facts in calls to the local check API. See Local Authorization for more information.