Skip to main content
Oso Cloud is stateful, like a database: it stores your policies and your authorization facts (e.g., role assignments, group memberships). As with any stateful system, there are times you will need to update the facts or policies stored in Oso Cloud.
Examples include:
  • Updating the hierarchy of resources during an application change.
  • Refactoring policy code to add new authorization features.
In these cases, you need to consider how the system behaves during the transition.

​
Example scenario: renaming a role

Suppose you have a simple RBAC setup where users can have roles on organizations: 
resource Org {
  roles = ["admin", "member"];

  "member" if "admin";

  "read" if "member";
  "delete" if "admin";
}
Now you want to rename the admin role to owner, perhaps to broaden admin capabilities and make it a distinct role. You cannot simply update the policy and replace all instances of admin with owner. If you did, the existing admins would lose their permissions until you updated the has_role facts to use owner roles. Because Oso policies are written in Polar, you can write temporary rules that bridge old facts to new ones, ensuring consistent authorization behavior during transitions.

​
Update steps

Follow these four steps to safely update facts and policies:
  1. Deploy new policy with bridge rules
Add temporary rules that map old facts to new facts. For example, map admin facts to owner facts: 
has_role(user: User, "owner", org: Org) if
  has_role(user, "admin", org);
  1. Deploy updated application code
Update your app to start writing owner facts to Oso Cloud. At this point, aside from the bridge rule above, no code or policy needs to reference admin facts. You could stop here if you are comfortable keeping the old admin facts. However, we recommend cleaning up both old facts and interim bridge rules.
  1. Batch update facts
Migrate old facts to new ones using the Get API with the Batch API: For each has_role(User, "admin", Org) fact, insert a corresponding has_role(User, "owner", Org) fact. If desired, clean up old facts with the Batch API as well with payload [{"deletes": <bulk_data>}].. Example workflow:
  • Fetch existing admin role facts with the Get API.
  • Insert new owner role facts and delete old admin facts with the Batch API.
  1. Remove bridge rules
Once all admin facts are fully replaced with owner facts, remove the temporary bridge rules from your policy.