Refactor authz resource tree (#103)

Author: paulineribeyre

.secrets.baseline

@@ -136,15 +136,6 @@
         "line_number": 15
       }
     ],
-    "alembic.ini": [
-      {
-        "type": "Basic Auth Credentials",
-        "filename": "alembic.ini",
-        "hashed_secret": "9d4e1e23bd5b727046a9e3b4b7db57bd8d6ee684",
-        "is_verified": false,
-        "line_number": 64
-      }
-    ],
     "docs/local_installation.md": [
       {
         "type": "Secret Keyword",
@@ -163,31 +154,13 @@
         "line_number": 55
       }
     ],
-    "migrations/versions/e1886270d9d2_create_system_key_table.py": [
-      {
-        "type": "Hex High Entropy String",
-        "filename": "migrations/versions/e1886270d9d2_create_system_key_table.py",
-        "hashed_secret": "1df47988c41b70d5541f29636c48c6127cf593b8",
-        "is_verified": false,
-        "line_number": 16
-      }
-    ],
     "tests/conftest.py": [
       {
         "type": "Base64 High Entropy String",
         "filename": "tests/conftest.py",
-        "hashed_secret": "0dd78d9147bb410f0cb0199c5037da36594f77d8",
-        "is_verified": false,
-        "line_number": 195
-      }
-    ],
-    "tests/migrations/test_migration_e1886270d9d2.py": [
-      {
-        "type": "Hex High Entropy String",
-        "filename": "tests/migrations/test_migration_e1886270d9d2.py",
-        "hashed_secret": "1df47988c41b70d5541f29636c48c6127cf593b8",
+        "hashed_secret": "06a9fa84e13b8f701d0c03235f675fee5e6fd736",
         "is_verified": false,
-        "line_number": 24
+        "line_number": 196
       }
     ],
     "tests/test-gen3workflow-config.yaml": [
@@ -209,5 +182,5 @@
       }
     ]
   },
-  "generated_at": "2026-02-27T22:12:14Z"
+  "generated_at": "2026-03-02T20:27:56Z"
 }

docs/authorization.md

@@ -3,22 +3,45 @@
 The Gen3 Workflow endpoints are protected by Arborist policies.
 
 Contents:
+- [Authorization resources overview](#authorization-resources-overview)
+- [Storage](#storage)
 - [GA4GH TES](#ga4gh-tes)
-  - [Authorization configuration example](#authorization-configuration-example)
+- [Authorization configuration example](#authorization-configuration-example)
+
+## Authorization resources overview
+
+```mermaid
+graph TD;
+    services --> workflow;
+    workflow --> gen3-workflow;
+    gen3-workflow --> tasks;
+    gen3-workflow --> storage;
+    tasks --> user1t(user1);
+    tasks --> user2t(user2);
+    storage --> user1;
+    storage --> user2;
+    user1t --> task1;
+    user1t --> task2;
+    user2t --> task3;
+```
 
 ## GA4GH TES
 
 - To create a task, users need `create` access to resource `/services/workflow/gen3-workflow/tasks` on service `gen3-workflow`.
-- To view a task, users need `read` access to resource `/users/<user ID>/gen3-workflow/tasks/<task ID>` on service `gen3-workflow`.
-  - Users are automatically granted access to `/users/<user ID>/gen3-workflow/tasks` so they can view their own tasks.
-  - Admin access (the ability to see _all_ users’ tasks instead of just your own) can be granted to a user by granting them access to the parent resource `/services/workflow/gen3-workflow/tasks`.
-  - This supports sharing tasks with others; for example, "user1" may share "taskA" with "user2" if the system grants "user2" access to `/users/user1/gen3-workflow/tasks/taskA`.
+- To view a task, users need `read` access to resource `/services/workflow/gen3-workflow/tasks/<user ID>/<task ID>` on service `gen3-workflow`.
+- To cancel a task, users need `delete` access to resource `/services/workflow/gen3-workflow/tasks/<user ID>/<task ID>` on service `gen3-workflow`.
+- Admin access (the ability to see _all_ users’ tasks instead of just your own) can be granted to a user by granting them access to the parent resource `/services/workflow/gen3-workflow/tasks`.
+- This supports sharing tasks with others; for example, "user1" may share "taskA" with "user2" if the system grants "user2" access to `/services/workflow/gen3-workflow/tasks/user1/taskA`.
+  - However, sharing task _inputs/outputs_ in the user's S3 bucket is not supported. Currently, users can only access their own S3 bucket.
 
-## Other Gen3-Workflow functionality
-- To download inputs and upload outputs, the Funnel workers need `create` access to resource `/services/workflow/gen3-workflow/tasks` on service `gen3-workflow`, like end-users.
-- To empty or delete their own S3 bucket, a user needs `delete` access to the resource `/services/workflow/gen3-workflow/user-bucket` on the `gen3-workflow` service -- a special privilege useful for automated testing but not intended for the average user.
+## Storage
+- To upload input files, download output files, and in general manage the files in their S3 bucket, users need `create`, `read` or `delete` access to resource `/services/workflow/gen3-workflow/storage/<user ID>` on service `gen3-workflow`.
+- The Funnel workers have access to `/services/workflow/gen3-workflow/storage` so they can manage files in all the user buckets.
+- To empty or delete their own S3 bucket (`/storage/user-bucket` endpoints), users need `delete` access to the resource `/services/workflow/gen3-workflow/storage/<user ID>` on the `gen3-workflow` service.
 
-#### Authorization configuration example
+## Authorization configuration example
+
+Users are automatically granted access to `/services/workflow/gen3-workflow/tasks/<user ID>` and to `/services/workflow/gen3-workflow/storage/<user ID>` so they can view and cancel their own tasks and manage files in their own bucket.
 
 ```yaml
 users:
@@ -29,7 +52,7 @@ users:
 clients:
   funnel-plugin-client:
     policies:
-    - gen3_workflow_user
+    - gen3_workflow_storage_admin
 
 authz:
   resources:
@@ -40,6 +63,7 @@ authz:
       - name: gen3-workflow
         subresources:
         - name: tasks
+        - name: storage
 
   policies:
   - id: gen3_workflow_user
@@ -48,18 +72,18 @@ authz:
     - gen3_workflow_creator
     resource_paths:
     - /services/workflow/gen3-workflow/tasks
-  - id: gen3_workflow_admin
+  - id: gen3_workflow_task_reader_admin
     description: Allows access to view tasks created by all users
     role_ids:
     - gen3_workflow_reader
     resource_paths:
     - /services/workflow/gen3-workflow/tasks
-  - id: workflow_storage_deleter
-    description: Allows delete access to the user's own S3 bucket
+  - id: gen3_workflow_storage_admin
+    description: Allows access to manage all the user buckets
     role_ids:
-    - workflow_storage_deleter
+    - gen3_workflow_admin
     resource_paths:
-    - /services/workflow/gen3-workflow
+    - /services/workflow/gen3-workflow/storage
 
   roles:
   - id: gen3_workflow_reader
@@ -74,10 +98,10 @@ authz:
       action:
         service: gen3-workflow
         method: create
-   - id: workflow_storage_deleter
-      permissions:
-      - id: workflow_storage_deleter
-        action:
-          service: gen3-workflow
-          method: delete
+  - id: gen3_workflow_admin
+    permissions:
+    - id: gen3_workflow_admin_action
+      action:
+        service: gen3-workflow
+        method: '*'
 ```

docs/helm_chart_architecture.md

@@ -8,7 +8,7 @@ The Gen3 Workflow helm chart is [here](https://github.com/uc-cdis/gen3-helm/tree
 
 ```mermaid
 graph TD;
-    A[Gen3 chart] --> B(Gen3 Workflow chart);
+    A(Gen3 chart) --> B(Gen3 Workflow chart);
     A --> C(Gen3 Funnel chart);
     C --> D(OHSU Funnel chart);
 ```

docs/local_installation.md

@@ -71,7 +71,7 @@ Try out the API at <http://localhost:8080/_status> or <http://localhost:8080/doc
 
 ## Run Nextflow workflows with Gen3Workflow
 
-- Hit the `/storage/info` endpoint to get your working directory
+- Hit the `/storage/setup` endpoint to get your working directory
 - Configure Nextflow. Example Nextflow configuration:
 ```
 plugins {

docs/openapi.yaml

@@ -498,20 +498,48 @@ paths:
       - S3
   /storage/info:
     get:
-      description: Get details about the current user's storage setup
-      operationId: get_storage_info
+      description: 'Return details about the current user''s storage setup.
+
+        This endpoint also serves as a mandatory "first time setup" for the user''s
+        bucket
+
+        and authz.'
+      operationId: storage_setup_2
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                additionalProperties: true
+                title: Response Storage Setup 2
+                type: object
+          description: Successful Response
+      security:
+      - HTTPBearer: []
+      summary: Storage Setup
+      tags:
+      - Storage
+  /storage/setup:
+    get:
+      description: 'Return details about the current user''s storage setup.
+
+        This endpoint also serves as a mandatory "first time setup" for the user''s
+        bucket
+
+        and authz.'
+      operationId: storage_setup
       responses:
         '200':
           content:
             application/json:
               schema:
                 additionalProperties: true
-                title: Response Get Storage Info
+                title: Response Storage Setup
                 type: object
           description: Successful Response
       security:
       - HTTPBearer: []
-      summary: Get Storage Info
+      summary: Storage Setup
       tags:
       - Storage
   /storage/user-bucket:

gen3workflow/auth.py

@@ -118,43 +118,52 @@ async def authorize(
 
         return authorized
 
-    async def grant_user_access_to_their_own_tasks(
+    async def grant_user_access_to_their_own_data(
         self, username: str, user_id: str
     ) -> None:
         """
         Ensure the specified user exists in Arborist and has a policy granting them access to their
-        own Gen3Workflow tasks ("read" and "delete" access to resource "/users/<user ID>/gen3-workflow/tasks" for service "gen3-workflow").
+        own Gen3Workflow tasks and bucket storage.
         Args:
             username (str): The user's Gen3 username
             user_id (str): The user's unique Gen3 ID
         """
-        logger.info(f"Ensuring user '{user_id}' has access to their own tasks")
-        resource_path = f"/users/{user_id}/gen3-workflow/tasks"
-        if await self.authorize(method="read", resources=[resource_path], throw=False):
-            # if the user already has access to their own tasks, return early
+        logger.info(
+            f"Ensuring user '{user_id}' has access to their own tasks and storage"
+        )
+        resource_path1 = f"/services/workflow/gen3-workflow/tasks/{user_id}"
+        if await self.authorize(method="read", resources=[resource_path1], throw=False):
+            # if the user already has access to their own data, return early
             return
 
-        logger.debug(f"Attempting to create resource '{resource_path}' in Arborist")
-        parent_path = f"/users/{user_id}/gen3-workflow"
+        parent_path = "/services/workflow/gen3-workflow/tasks"
+        logger.debug(f"Attempting to create resource '{resource_path1}' in Arborist")
         resource = {
-            "name": "tasks",
+            "name": user_id,
             "description": f"Represents workflow tasks owned by user '{username}'",
         }
         await self.arborist_client.create_resource(
             parent_path, resource, create_parents=True
         )
 
-        role_id = "gen3-workflow_task_owner"
+        resource_path2 = f"/services/workflow/gen3-workflow/storage/{user_id}"
+        parent_path = "/services/workflow/gen3-workflow/storage"
+        logger.debug(f"Attempting to create resource '{resource_path2}' in Arborist")
+        resource = {
+            "name": user_id,
+            "description": f"Represents task storage owned by user '{username}'",
+        }
+        await self.arborist_client.create_resource(
+            parent_path, resource, create_parents=True
+        )
+
+        role_id = "gen3_workflow_admin"
         role = {
             "id": role_id,
             "permissions": [
                 {
-                    "id": "gen3-workflow-reader",
-                    "action": {"service": "gen3-workflow", "method": "read"},
-                },
-                {
-                    "id": "gen3-workflow-deleter",
-                    "action": {"service": "gen3-workflow", "method": "delete"},
+                    "id": "gen3_workflow_admin_action",
+                    "action": {"service": "gen3-workflow", "method": "*"},
                 },
             ],
         }
@@ -168,13 +177,13 @@ async def grant_user_access_to_their_own_tasks(
             )
             await self.arborist_client.create_role(role)
 
-        policy_id = f"gen3-workflow_task_owner_sub-{user_id}"
+        policy_id = f"gen3_workflow_user_sub_{user_id}"
         logger.debug(f"Attempting to create policy '{policy_id}' in Arborist")
         policy = {
             "id": policy_id,
             "description": f"policy created by gen3-workflow for user '{username}'",
             "role_ids": [role_id],
-            "resource_paths": [resource_path],
+            "resource_paths": [resource_path1, resource_path2],
         }
         await self.arborist_client.create_policy(policy, skip_if_exists=True)
 

gen3workflow/aws_utils.py

@@ -226,7 +226,7 @@ def create_iam_role_for_bucket_access(user_id: str) -> str:
     if config["KMS_ENCRYPTION_ENABLED"]:
         _, kms_key_arn = get_existing_kms_key_for_bucket(bucket_name)
         if not kms_key_arn:
-            err_msg = "Bucket misconfigured. Hit the `GET /storage/info` endpoint and try again."
+            err_msg = "Bucket misconfigured. Hit the `GET /storage/setup` endpoint and try again."
             logger.error(
                 f"No existing KMS key found for bucket '{bucket_name}'. {err_msg}"
             )

gen3workflow/routes/ga4gh_tes.py

@@ -149,7 +149,10 @@ async def create_task(request: Request, auth=Depends(Auth)) -> dict:
         err_msg = f"Tags {sorted(reserved_tags)} are reserved for internal use only and cannot be used."
         logger.error(err_msg)
         raise HTTPException(HTTP_400_BAD_REQUEST, err_msg)
-    body["tags"]["_AUTHZ"] = f"/users/{user_id}/gen3-workflow/tasks/TASK_ID_PLACEHOLDER"
+    authz_resource = (
+        f"/services/workflow/gen3-workflow/tasks/{user_id}/TASK_ID_PLACEHOLDER"
+    )
+    body["tags"]["_AUTHZ"] = authz_resource
     # TODO: Test running gen3-workflow locally and document this change
     if config["EKS_CLUSTER_NAME"]:
         body["tags"]["_FUNNEL_WORKER_ROLE_ARN"] = (
@@ -166,14 +169,6 @@ async def create_task(request: Request, auth=Depends(Auth)) -> dict:
         headers={"Authorization": f"bearer {auth.bearer_token.credentials}"},
     )
 
-    try:
-        await auth.grant_user_access_to_their_own_tasks(
-            username=username, user_id=user_id
-        )
-    except ArboristError as e:
-        logger.error(e.message)
-        raise HTTPException(e.code, e.message)
-
     return res.json()