improve doc

Author: bwalsh

docs/rbac.md

@@ -31,28 +31,30 @@ and inject resources (projects) into query.
 - [x] add new tests specific to RBAC
 - [x] Add feature flag to [default_settings](https://github.com/uc-cdis/indexd/blob/8ff50b9c829920907181d5c186c907e06f5c4a5d/indexd/default_settings.py)
 - [x] Remove extraneous logging and debugging code
-- [ ] Ensure ARE_RECORDS_DISCOVERABLE, GLOBAL_DISCOVERY_AUTHZ See [discussion](https://github.com/uc-cdis/indexd/pull/400#discussion_r2243579240)
+- [x] Ensure ARE_RECORDS_DISCOVERABLE, GLOBAL_DISCOVERY_AUTHZ See [discussion](https://github.com/uc-cdis/indexd/pull/400#discussion_r2243579240)
 - [ ] Add a corresponding feature flag to helm chart
 
 ---
-# reviewers guide
 
-## Code Review
+## Implementation Overview
+
 * Main changes were made to:
   * indexd/auth
   * indexd/index/drivers/alchemy.py
-* All of the changes above:
+
+* All the changes above:
   * should be transparent to the user, and they should not notice any difference in behavior.
   * should be non-breaking, as it only changes the behavior when the `authz` parameter is empty.
   * However, it will throw a 401/403 is the user does not have access to the requested resource,or does not have and Authorization header which is a change from the previous behavior where it would return all the records regardless of the user's access.
+
 * "Breaking" Changes:
   * In order to enforce authorization, we need to ensure that all records have an `authz` field.
   * (This is not a change in behavior to OHSU/ACED/Calypr, but it is a change in behavior to the Indexd API in that effectively authz is mandatory on write)
+
 * Misc:
   * Added stack traces to log for unhandled exceptions see changes to blueprint.py for various endpoints
-* Tests:
 
-**Architecture Rationale for `tests/rbac`**
+## **Testing  `tests/rbac`**
 
 The `tests/rbac` suite is designed to validate RBAC-aware behavior in the indexd service, while ensuring the stability and integrity of legacy functionality. The following principles guide its architecture:
 
@@ -68,7 +70,26 @@ The `tests/rbac` suite is designed to validate RBAC-aware behavior in the indexd
 - **Mocked Authorization Backend:**  
   Arborist responses are mocked to provide deterministic and isolated test scenarios, enabling reliable validation of access control logic without external dependencies.
 
-- **Feature Flag Validation:**  
+## **Configuration:**  
   Tests verify both enabled and disabled states of the RBAC feature flag, confirming that the system defaults to legacy behavior unless explicitly configured otherwise.
 
+  * `ARE_RECORDS_DISCOVERABLE`
+  
+  - **Type:** `bool`
+    - **Default:** `True`
+    - **Description:**  
+      Controls whether any records in IndexD are discoverable via search or listing endpoints.  
+      If set to `False`, all records are hidden from discovery, regardless of their individual authorization settings.  
+      Note: Role-Based Access Control (RBAC) is not enabled by default.
+  
+  * `GLOBAL_DISCOVERY_AUTHZ`
+  
+  - **Type:** `list` or `None`
+    - **Default:** `[]`
+    - **Description:**  
+      Overrides per-record authorization for GET/read operations during record discovery.  
+      If set to a list of authorization requirements, these are applied globally to all records for discovery purposes.  
+      If set to `None`, the system uses each record's individual `authz` field for authorization checks.  
+      This setting does not affect file access permissions, only record discovery.
+
 This approach ensures robust coverage of the new RBAC functionality while maintaining the integrity and reliability of the existing test suite.