changelog for Polar roles implementation
@@ -50,10 +50,40 @@ allow(_user, action, repository: Repository) if
##### Built-in Role-Based Access Control (RBAC) policy
-<!-- TODO(gj): usual caveat about this being an experimental feature; talk to us
-if you want to use it in prod. -->
+Oso's Python and Node libraries now include [built-in support for Role-Based Access Control (RBAC) policies](/guides/roles).
+The goal of introducing this feature is to make setting up common role-based access control patterns even easier
+by providing a structured configuration interface and implementing the query evaluation logic.
+
+Here's an example policy using the new configuration interface:
+
+```polar
+resource(_type: Org, "org", actions, roles) if
+ actions = ["read", "create_repo"] and
+ roles = {
+ member: {
+ permissions: ["read"],
+ },
+ owner: {
+ permissions: ["read", "create_repo"],
+ }
+ };
+```
+
+The configuration interface allows Oso users to:
+- Define **resource types** and **roles** that are used to control access to individual resources of that type (resource-specific roles)
+ - E.g., users can define `Organization` resources that have `"owner"`, `"member"`, and `"billing"` roles.
+- Define the **actions** that each role allows users to take
+ - E.g., the `"owner"` role for an `Organization` allows users to take the `"invite_member"` action for that particular organization
+- Define parent-child relationships between resources to enable features like **implied roles and nested permissions**
+ - E.g., if a user has the `"owner"` role on an organization, they also have the `"admin"` role implied for every child repository of the organization
+
+In order to use the built-in policy, Oso users must store user-role assignments themselves and implement a simple interface to expose the user-role assignment data to Oso's policy engine.
+
+Then, the role-based policy will be evaluated as any other policy would by calling the `is_allowed()` library method.
+
+To get started, check out [the docs](/guides/roles).
+
-<!-- TODO(gj): link to new docs -->
### Ruby
