Oso

Oso is an authorization service that models roles, relationships and attributes in its Polar policy language. Behind access, your Oso policies decide and MainSDK adds typed checks, fail-closed behaviour and audit. Pick it when your team already models permissions in Oso.

access:
  driver: oso

Before you start

1. Set up Oso for your app and write your policy.
2. Create an API key for each environment and keep it in your secrets manager.

Configure

access:
  driver: oso
  models: [rbac, rebac]
  unreachable: { deny: true, cache: 30s }
  # [to be decided] connection keys; suggested secret: OSO_API_KEY

Use it

import { access } from "mainsdk";

const decision = await access.check({ subject: user, action: "repos.write", resource: repo });
if (!decision.allow) throw new Error("forbidden");

Local development and testing

Build on in-process Cedar with mainsdk dev. createTestApp() from @mainsdk/testing puts access on its fake, and chaos.on("access", { outage: true }) shows checks denying with MAIN-ACCESS-0007.

What MainSDK adds on top

• Deny by default, with no bypass path.
• Denies when Oso is unreachable, with only a short cache you set.
• Lists filtered at the database, not after fetching rows.
• Every decision written to the audit log with the policy version.

See Permissions.

Limits and notes

• The access spec lists Oso as a driver that comes later in phases 1-2 through the driver kit, beyond its capability profile.
• Which models the driver supports is declared in its capability profile; mainsdk check names any gap with MAIN-ACCESS-0004.
• access.raw() returns the Oso client; mainsdk check lists every use.

Swap to or from it

access:
  driver: cedar   # was oso

FAQ

Do I rewrite my Polar policy? Not to adopt the driver. Only if you later move to another engine.

Next

• Permissions
• Cerbos and Permit.io
• Swap a driver