Create roles page (#323)

* Create roles page

* Address comments

* Replicate across versions

Author: nenharper

docs/developers/applications/defining-roles.md

@@ -1,54 +1,85 @@
 ---
-title: Defining Roles
+title: Defining Application Roles
 ---
 
-In addition to [defining a database schema](./defining-schemas), you can also define roles in your application. Roles are a way to group permissions together and assign them to users as part of Harper's [role based access control](../security/users-and-roles). An application component may declare roles that should exist for the application in a roles configuration file. To use this, first specify your roles config file in the `config.yaml` in your application directory:
+# Defining Application Roles
+
+Applications are more than just tables and endpoints — they need access rules. Harper lets you define roles directly in your application so you can control who can do what, without leaving your codebase.
+
+Let’s walk through creating a role, assigning it, and seeing it in action.
+
+## Step 1: Declare a Role
+
+First, point Harper to a roles configuration file. Add this to your `config.yaml`:
 
 ```yaml
 roles:
   files: roles.yaml
 ```
 
-Now you can create a roles.yaml in your application directory:
+Then create a simple `roles.yaml` in your application directory. For example, here’s a role that can only read and insert data into the `Dog` table:
 
 ```yaml
-declared-role:
-  super_user: false # This is a boolean value that indicates if the role is a super user or not
-  # Now we can grant the permissions to databases, here we grant permissions to the default data database
-  data: # This is the same structure as role object that is used in the roles operations APIs
-    TableOne:
+dog-reader:
+  super_user: false
+  data:
+    Dog:
       read: true
       insert: true
-    TableTwo:
-      read: true
-      insert: false
-      update: true
-      delete: true
-      attributes:
-        name:
-          read: true
-          insert: false
-          update: true
 ```
 
-With this in place, where Harper starts up, it will create the roles in the roles.yaml file if they do not already exist. If they do exist, it will update the roles with the new permissions. This allows you to manage your roles in your application code and have them automatically created or updated when the application starts.
+When Harper starts up, it will create this role (or update it if it already exists).
 
-The structure of the roles.yaml file is:
+## Step 2: Create a User for the Role
 
-```yaml
-<role-name>:
-  permission: # contains the permissions for the role, this structure is optional, and you can place flags like super_user here as a shortcut
-    super_user: <boolean>
-  <database-name>: # each database with permissions can be added as named properties on the role
-  tables: # this structure is optional, and table names can be placed directly under the database as a shortcut
-    <table-name>:
-      read: <boolean> # indicates if the role has read permission to this table
-      insert: <boolean> # indicates if the role has insert permission to this table
-      update: <boolean> # indicates if the role has update permission to this table
-      delete: <boolean> # indicates if the role has delete permission to this table
-      attributes:
-        <attribute-name>: # individual attributes can have permissions as well
-          read: <boolean>
-          insert: <boolean>
-          update: <boolean>
+Next, create a non-super_user user and assign them this role. You can do this with the [Users and Roles API](../security/users-and-roles) (requires a super_user to run):
+
+```bash
+curl -u admin:password -X POST http://localhost:9926 \
+  -H "Content-Type: application/json" \
+  -d '{
+    "operation": "add_user",
+    "username": "alice",
+    "password": "password",
+    "role": "dog_reader"
+  }'
 ```
+
+Now you have a user named `alice` with the `dog_reader` role.
+
+## Step 3: Make Requests as Different Users
+
+Authenticate requests as `alice` to see how her role works:
+
+```bash
+# allowed (insert, role permits insert)
+curl -u alice:password -X POST http://localhost:9926/Dog/ \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Buddy", "breed": "Husky"}'
+
+# not allowed (delete, role does not permit delete)
+curl -u alice:password -X DELETE http://localhost:9926/Dog/1
+```
+
+The first request succeeds with a `200 OK`. The second fails with a `403 Forbidden`.
+
+Now compare with a super_user:
+
+```bash
+# super_user can delete
+curl -u admin:password -X DELETE http://localhost:9926/Dog/1
+```
+
+This succeeds because the super_user role has full permissions.
+
+## Where to Go Next
+
+This page gave you the basics - declare a role, assign it, and see it work.
+
+For more advanced scenarios, including:
+
+- defining multiple databases per role,
+- granting fine-grained attribute-level permissions,
+- and the complete structure of `roles.yaml`,
+
+see the [Roles Reference](../../reference/Applications/defining-roles).

docs/reference/Applications/defining-roles.md

@@ -0,0 +1,117 @@
+---
+title: Defining Application Roles
+---
+
+# Defining Application Roles
+
+Roles in Harper are part of the application’s role-based access control (RBAC) system. You can declare roles in your application and manage their permissions through a roles configuration file. When the application starts, Harper will ensure all declared roles exist with the specified permissions, updating them if necessary.
+
+## Configuring Roles
+
+Point to a roles configuration file from your application’s `config.yaml`:
+
+```yaml
+roles:
+  files: roles.yaml
+```
+
+You can declare one or more files. Each file should define one or more roles in YAML format.
+
+## Roles File Structure
+
+A roles file (`roles.yaml`) contains role definitions keyed by role name. Each role may contain:
+
+- **super_user** – a boolean that grants all permissions.
+- **databases** – one or more databases the role has access to.
+- **tables** – within each database, table-level and attribute-level permissions.
+
+**Full Example**
+
+```yaml
+<role-name>:
+  super_user: <boolean> # optional
+  <database-name>:
+    <table-name>:
+      read: <boolean>
+      insert: <boolean>
+      update: <boolean>
+      delete: <boolean>
+      attributes:
+        <attribute-name>:
+          read: <boolean>
+          insert: <boolean>
+          update: <boolean>
+```
+
+## Role Flags
+
+- `super_user: true` — grants full system access.
+- `super_user: false` — the role only has the explicit permissions defined in the role.
+
+## Database and Table Permissions
+
+Within each role, you may specify one or more databases. Each database can declare permissions for tables.
+
+Example:
+
+```yaml
+analyst:
+  super_user: false
+  data:
+    Sales:
+      read: true
+      insert: false
+      update: false
+      delete: false
+```
+
+In this example, the `analyst` role has read-only access to the `Sales` table in the `data` database.
+
+## Attribute-Level Permissions
+
+You can also grant or deny access at the attribute level within a table.
+
+Example:
+
+```yaml
+editor:
+  data:
+    Articles:
+      read: true
+      insert: true
+      update: true
+      attributes:
+        title:
+          read: true
+          update: true
+        author:
+          read: true
+          update: false
+```
+
+Here, the `editor` role can update the `title` of an article but cannot update the `author`.
+
+## Multiple Roles
+
+Roles can be defined side by side in a single file:
+
+```yaml
+reader:
+  super_user: false
+  data:
+    Dog:
+      read: true
+
+writer:
+  super_user: false
+  data:
+    Dog:
+      insert: true
+      update: true
+```
+
+## Behavior on Startup
+
+- If a declared role does not exist, Harper creates it.
+- If a declared role already exists, Harper updates its permissions to match the definition.
+- Roles are enforced consistently across deployments, keeping access control in sync with your application code.

versioned_docs/version-4.4/developers/applications/defining-roles.md

@@ -1,54 +1,85 @@
 ---
-title: Defining Roles
+title: Defining Application Roles
 ---
 
-In addition to [defining a database schema](./defining-schemas), you can also define roles in your application. Roles are a way to group permissions together and assign them to users as part of Harper's [role based access control](../security/users-and-roles). An application component may declare roles that should exist for the application in a roles configuration file. To use this, first specify your roles config file in the `config.yaml` in your application directory:
+# Defining Application Roles
+
+Applications are more than just tables and endpoints — they need access rules. Harper lets you define roles directly in your application so you can control who can do what, without leaving your codebase.
+
+Let’s walk through creating a role, assigning it, and seeing it in action.
+
+## Step 1: Declare a Role
+
+First, point Harper to a roles configuration file. Add this to your `config.yaml`:
 
 ```yaml
 roles:
   files: roles.yaml
 ```
 
-Now you can create a roles.yaml in your application directory:
+Then create a simple `roles.yaml` in your application directory. For example, here’s a role that can only read and insert data into the `Dog` table:
 
 ```yaml
-declared-role:
-  super_user: false # This is a boolean value that indicates if the role is a super user or not
-  # Now we can grant the permissions to databases, here we grant permissions to the default data database
-  data: # This is the same structure as role object that is used in the roles operations APIs
-    TableOne:
+dog-reader:
+  super_user: false
+  data:
+    Dog:
       read: true
       insert: true
-    TableTwo:
-      read: true
-      insert: false
-      update: true
-      delete: true
-      attributes:
-        name:
-          read: true
-          insert: false
-          update: true
 ```
 
-With this in place, where Harper starts up, it will create the roles in the roles.yaml file if they do not already exist. If they do exist, it will update the roles with the new permissions. This allows you to manage your roles in your application code and have them automatically created or updated when the application starts.
+When Harper starts up, it will create this role (or update it if it already exists).
 
-The structure of the roles.yaml file is:
+## Step 2: Create a User for the Role
 
-```yaml
-<role-name>:
-  permission: # contains the permissions for the role, this structure is optional, and you can place flags like super_user here as a shortcut
-    super_user: <boolean>
-  <database-name>: # each database with permissions can be added as named properties on the role
-  tables: # this structure is optional, and table names can be placed directly under the database as a shortcut
-    <table-name>:
-      read: <boolean> # indicates if the role has read permission to this table
-      insert: <boolean> # indicates if the role has insert permission to this table
-      update: <boolean> # indicates if the role has update permission to this table
-      delete: <boolean> # indicates if the role has delete permission to this table
-      attributes:
-        <attribute-name>: # individual attributes can have permissions as well
-          read: <boolean>
-          insert: <boolean>
-          update: <boolean>
+Next, create a non-super_user user and assign them this role. You can do this with the [Users and Roles API](../security/users-and-roles) (requires a super_user to run):
+
+```bash
+curl -u admin:password -X POST http://localhost:9926 \
+  -H "Content-Type: application/json" \
+  -d '{
+    "operation": "add_user",
+    "username": "alice",
+    "password": "password",
+    "role": "dog_reader"
+  }'
 ```
+
+Now you have a user named `alice` with the `dog_reader` role.
+
+## Step 3: Make Requests as Different Users
+
+Authenticate requests as `alice` to see how her role works:
+
+```bash
+# allowed (insert, role permits insert)
+curl -u alice:password -X POST http://localhost:9926/Dog/ \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Buddy", "breed": "Husky"}'
+
+# not allowed (delete, role does not permit delete)
+curl -u alice:password -X DELETE http://localhost:9926/Dog/1
+```
+
+The first request succeeds with a `200 OK`. The second fails with a `403 Forbidden`.
+
+Now compare with a super_user:
+
+```bash
+# super_user can delete
+curl -u admin:password -X DELETE http://localhost:9926/Dog/1
+```
+
+This succeeds because the super_user role has full permissions.
+
+## Where to Go Next
+
+This page gave you the basics - declare a role, assign it, and see it work.
+
+For more advanced scenarios, including:
+
+- defining multiple databases per role,
+- granting fine-grained attribute-level permissions,
+- and the complete structure of `roles.yaml`,
+
+see the [Roles Reference](../../reference/Applications/defining-roles).