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:

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"

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() or request_came_from_eu().

For an account of when to use 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:

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

Related content

• Facts: The Oso Cloud data model