Skip to content

Commit 97217b9

Browse files
BryanFaubleBryanFauble
committed
Cleaning up code and bug bashing, adding in sharing settings tutorial, moving mermaid diagram, updating docstrings, expanding tests, make getting current ACL easier
1 parent 928e29e commit 97217b9

File tree

14 files changed

+1492
-204
lines changed

14 files changed

+1492
-204
lines changed

‎docs/explanations/access_control.md

Lines changed: 82 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,88 @@
11
# Access Control
22

3-
By default, data sets in Synapse are private to your user account, but they can easily be shared with specific users, groups, or the public.
3+
Access Control Lists (ACLs) in Synapse are the foundation of data security and sharing. They determine who can access your data and what actions they can perform. By default, all entities in Synapse are private to your user account, but they can be easily shared with specific users, groups, or made publicly accessible.
44

5-
See:
5+
## Core Concepts
66

7+
### Access Control Lists (ACLs)
8+
An ACL is a set of permissions that define what actions specific users or groups can perform on a Synapse entity. Each ACL entry specifies:
9+
10+
- **Principal**: The user, team, or special group being granted permissions
11+
- **Permissions**: The specific actions they can perform
12+
13+
### Benefactors and Inheritance
14+
Every entity in Synapse has a **benefactor** - the entity from which it inherits its permissions:
15+
16+
- **Default Inheritance**: New entities inherit permissions from their parent container
17+
- **Local ACLs**: When you create custom sharing settings, the entity becomes its own benefactor
18+
- **Permission Resolution**: Synapse traverses up the hierarchy to find the benefactor with ACL settings
19+
20+
### Permission Types
21+
Synapse supports several permission types that can be combined:
22+
23+
- **READ**: View entity metadata and basic information
24+
- **DOWNLOAD**: Download files and data (requires READ)
25+
- **UPDATE**: Modify entity metadata and upload new file versions
26+
- **CREATE**: Create new entities within containers
27+
- **DELETE**: Delete entities
28+
- **CHANGE_PERMISSIONS**: Modify ACL permissions
29+
- **CHANGE_SETTINGS**: Modify entity settings
30+
- **MODERATE**: Moderate forum discussions (for projects)
31+
32+
### Special Principal IDs
33+
Synapse provides special principals for common sharing scenarios:
34+
35+
- **273948**: All authenticated Synapse users
36+
- **273949**: Public access (anyone on the internet)
37+
- **Specific User ID**: Individual Synapse users (e.g., 3417048)
38+
- **Team ID**: Synapse teams for group-based permissions
39+
40+
## Common Use Cases
41+
42+
### Research Collaboration
43+
- **Internal Teams**: Grant READ/DOWNLOAD to collaborators
44+
- **Data Owners**: Maintain full permissions (including UPDATE/DELETE)
45+
- **Public Data**: Use public principal (273949) for open datasets
46+
47+
### Hierarchical Access Control
48+
- **Project Level**: Set broad permissions for the entire project
49+
- **Folder Level**: Override with more restrictive permissions for sensitive data
50+
- **File Level**: Fine-grained control for specific datasets
51+
52+
### Data Governance
53+
- **Sensitive Data**: Create local ACLs with restricted access
54+
- **Compliance**: Use teams for role-based access control
55+
- **Auditing**: Use `list_acl()` to review permission structures
56+
57+
## Best Practices
58+
59+
1. **Use Inheritance**: Leverage the default inheritance model when possible for easier management
60+
2. **Minimal Local ACLs**: Only create custom ACLs when you need different permissions than the parent
61+
3. **Team-Based Permissions**: Use Synapse teams for group permissions rather than individual users
62+
4. **Regular Audits**: Periodically review ACLs using `list_acl()` to ensure appropriate access
63+
5. **Dry Run Testing**: Use `dry_run=True` when deleting permissions to preview changes
64+
6. **Documentation**: Document your permission structure for team understanding
65+
66+
## Security Considerations
67+
68+
- **Principle of Least Privilege**: Grant only the minimum permissions necessary
69+
- **Regular Reviews**: Audit permissions regularly, especially for sensitive data
70+
- **Team Management**: Use teams to simplify permission management and reduce errors
71+
- **Public Access**: Be cautious when granting public access (273949) to ensure data is appropriate for public consumption
72+
73+
## Learn More
74+
75+
For hands-on experience with ACL management, follow the comprehensive [Sharing Settings Tutorial](../tutorials/python/sharing_settings.md), which demonstrates all aspects of permission management using real examples.
76+
77+
## API References
78+
79+
### Object-Oriented Models
80+
- [get_permissions()][synapseclient.models.protocols.access_control_protocol.AccessControllableSynchronousProtocol.get_permissions]
81+
- [get_acl()][synapseclient.models.protocols.access_control_protocol.AccessControllableSynchronousProtocol.get_acl]
82+
- [set_permissions()][synapseclient.models.protocols.access_control_protocol.AccessControllableSynchronousProtocol.set_permissions]
83+
- [list_acl()][synapseclient.models.protocols.access_control_protocol.AccessControllableSynchronousProtocol.list_acl]
84+
- [delete_permissions()][synapseclient.models.protocols.access_control_protocol.AccessControllableSynchronousProtocol.delete_permissions]
85+
86+
### Legacy API Methods
787
- [synapseclient.Synapse.getPermissions][]
888
- [synapseclient.Synapse.setPermissions][]

‎docs/reference/experimental/async/table.md

Lines changed: 0 additions & 138 deletions
Original file line numberDiff line numberDiff line change
@@ -65,141 +65,3 @@ at your own risk.
6565
::: synapseclient.models.CsvTableDescriptor
6666
[](){ #csv-to-pandas-df-reference-async }
6767
::: synapseclient.models.mixins.table_components.csv_to_pandas_df
68-
69-
## delete_permissions_async Flow Diagram
70-
71-
The following sequence diagram illustrates the complete flow and function calls of the `delete_permissions_async` method:
72-
73-
```mermaid
74-
sequenceDiagram
75-
participant User as User/Client
76-
participant Entity as Entity (File/Folder/Project)
77-
participant Tracker as BenefactorTracker
78-
participant SynClient as Synapse Client
79-
participant API as Synapse API
80-
participant Logger as Logger
81-
82-
User->>Entity: delete_permissions_async(params)
83-
84-
Note over Entity: Parameter Validation & Setup
85-
Entity->>Entity: Validate entity.id exists
86-
Entity->>SynClient: get_client()
87-
88-
alt Project Entity
89-
Entity->>Logger: warn("Project ACL cannot be deleted")
90-
Entity->>Entity: set include_self=False
91-
end
92-
93-
Entity->>Entity: _normalize_target_entity_types()
94-
Entity->>Tracker: create BenefactorTracker()
95-
96-
alt Recursive or Container Content Processing
97-
Entity->>Entity: _collect_entities()
98-
Note over Entity: Gather all entities to process
99-
100-
Entity->>Tracker: track_entity_benefactor(entity_ids)
101-
102-
loop For each entity_id
103-
Tracker->>API: get_entity_benefactor(entity_id)
104-
API-->>Tracker: benefactor_result
105-
end
106-
107-
Note over Tracker: Build benefactor relationships
108-
Tracker->>Tracker: Update entity_benefactors mapping
109-
Tracker->>Tracker: Update benefactor_children mapping
110-
end
111-
112-
alt Dry Run Mode
113-
Entity->>Entity: _build_and_log_dry_run_tree()
114-
Entity->>Logger: Log what would be deleted
115-
Entity-->>User: Return (no actual deletion)
116-
else Actual Deletion
117-
118-
alt Include Self
119-
Entity->>Entity: _delete_current_entity_acl()
120-
121-
Entity->>Tracker: track_entity_benefactor([self.id])
122-
Tracker->>API: get_entity_benefactor(self.id)
123-
API-->>Tracker: benefactor_result
124-
125-
Entity->>Tracker: will_acl_deletion_affect_others(self.id)
126-
Tracker-->>Entity: boolean result
127-
128-
alt Will Affect Others
129-
Entity->>Logger: info("Deleting ACL will affect X entities")
130-
end
131-
132-
Entity->>API: delete_entity_acl(self.id)
133-
134-
alt Success
135-
API-->>Entity: Success
136-
Entity->>Logger: debug("Deleted ACL for entity")
137-
Entity->>Tracker: mark_acl_deleted(self.id)
138-
Tracker->>Tracker: Update benefactor relationships
139-
Tracker-->>Entity: affected_entities list
140-
141-
alt Has Affected Entities
142-
Entity->>Logger: info("ACL deletion caused X entities to inherit from new benefactor")
143-
end
144-
else HTTP Error
145-
API-->>Entity: SynapseHTTPError
146-
alt Already Inherits (403)
147-
Entity->>Logger: debug("Entity already inherits permissions")
148-
else Other Error
149-
Entity->>Entity: raise exception
150-
end
151-
end
152-
end
153-
154-
alt Process Container Contents
155-
Entity->>Entity: _process_container_contents()
156-
157-
alt Process Files
158-
loop For each file
159-
Entity->>Entity: file.delete_permissions_async(recursive=False)
160-
Note right of Entity: Recursive call for each file
161-
end
162-
end
163-
164-
alt Process Folders
165-
Entity->>Entity: _process_folder_permission_deletion()
166-
167-
loop For each folder
168-
alt Recursive Mode
169-
Entity->>Entity: folder.delete_permissions_async(recursive=True)
170-
else Direct Mode
171-
Entity->>Entity: folder.delete_permissions_async(recursive=False)
172-
end
173-
Note right of Entity: Recursive calls for folders
174-
end
175-
end
176-
end
177-
end
178-
179-
Entity-->>User: Complete
180-
181-
Note over User,Logger: Key Features:
182-
Note over User,Logger: • Async operations with asyncio.gather()
183-
Note over User,Logger: • Benefactor relationship tracking
184-
Note over User,Logger: • Recursive processing capabilities
185-
Note over User,Logger: • Dry run mode for preview
186-
Note over User,Logger: • Error handling for inheritance conflicts
187-
Note over User,Logger: • Cascading permission updates
188-
```
189-
190-
### Key Components:
191-
192-
- **Entity**: The primary object (File, Folder, Project) whose permissions are being deleted
193-
- **BenefactorTracker**: Manages benefactor relationships and tracks cascading changes
194-
- **Synapse Client**: Handles API communication and logging
195-
- **Synapse API**: REST endpoints for ACL operations (`delete_entity_acl`, `get_entity_benefactor`)
196-
- **Logger**: Records operations, warnings, and debug information
197-
198-
### Flow Highlights:
199-
200-
1. **Validation Phase**: Parameter validation and client setup
201-
2. **Collection Phase**: Gathering entities for recursive operations
202-
3. **Tracking Phase**: Parallel benefactor relationship discovery
203-
4. **Preview Phase**: Dry run mode shows what would be deleted
204-
5. **Deletion Phase**: Actual ACL deletions with error handling
205-
6. **Cascading Phase**: Updates benefactor relationships for affected entities

‎docs/reference/experimental/mixins/access_controllable.md

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,147 @@
11
# AccessControllable
22

3+
## delete_permissions Flow Diagram
4+
5+
The following sequence diagram illustrates the complete flow and function calls of the `delete_permissions` method:
6+
7+
```mermaid
8+
sequenceDiagram
9+
participant User as User/Client
10+
participant Entity as Entity (File/Folder/Project)
11+
participant Tracker as BenefactorTracker
12+
participant SynClient as Synapse Client
13+
participant API as Synapse API
14+
participant Logger as Logger
15+
16+
User->>Entity: delete_permissions(params)
17+
18+
Note over Entity: Parameter Validation & Setup
19+
Entity->>Entity: Validate entity.id exists
20+
Entity->>SynClient: get_client()
21+
22+
alt Project Entity
23+
Entity->>Logger: warn("Project ACL cannot be deleted")
24+
Entity->>Entity: set include_self=False
25+
end
26+
27+
Entity->>Entity: _normalize_target_entity_types()
28+
Entity->>Tracker: create BenefactorTracker()
29+
30+
alt Recursive or Container Content Processing
31+
Entity->>Entity: _collect_entities()
32+
Note over Entity: Gather all entities to process
33+
34+
Entity->>Tracker: track_entity_benefactor(entity_ids)
35+
36+
loop For each entity_id
37+
Tracker->>API: get_entity_benefactor(entity_id)
38+
API-->>Tracker: benefactor_result
39+
end
40+
41+
Note over Tracker: Build benefactor relationships
42+
Tracker->>Tracker: Update entity_benefactors mapping
43+
Tracker->>Tracker: Update benefactor_children mapping
44+
end
45+
46+
alt Dry Run Mode
47+
Entity->>Entity: _build_and_log_dry_run_tree()
48+
Entity->>Logger: Log what would be deleted
49+
Entity-->>User: Return (no actual deletion)
50+
else Actual Deletion
51+
52+
alt Include Self
53+
Entity->>Entity: _delete_current_entity_acl()
54+
55+
Entity->>Tracker: track_entity_benefactor([self.id])
56+
Tracker->>API: get_entity_benefactor(self.id)
57+
API-->>Tracker: benefactor_result
58+
59+
Entity->>Tracker: will_acl_deletion_affect_others(self.id)
60+
Tracker-->>Entity: boolean result
61+
62+
alt Will Affect Others
63+
Entity->>Logger: info("Deleting ACL will affect X entities")
64+
end
65+
66+
Entity->>API: delete_entity_acl(self.id)
67+
68+
alt Success
69+
API-->>Entity: Success
70+
Entity->>Logger: debug("Deleted ACL for entity")
71+
Entity->>Tracker: mark_acl_deleted(self.id)
72+
Tracker->>Tracker: Update benefactor relationships
73+
Tracker-->>Entity: affected_entities list
74+
75+
alt Has Affected Entities
76+
Entity->>Logger: info("ACL deletion caused X entities to inherit from new benefactor")
77+
end
78+
else HTTP Error
79+
API-->>Entity: SynapseHTTPError
80+
alt Already Inherits (403)
81+
Entity->>Logger: debug("Entity already inherits permissions")
82+
else Other Error
83+
Entity->>Entity: raise exception
84+
end
85+
end
86+
end
87+
88+
alt Process Container Contents
89+
Entity->>Entity: _process_container_contents()
90+
91+
alt Process Files
92+
loop For each file
93+
Entity->>Entity: file.delete_permissions_async(recursive=False)
94+
Note right of Entity: Recursive call for each file
95+
end
96+
end
97+
98+
alt Process Folders
99+
Entity->>Entity: _process_folder_permission_deletion()
100+
101+
loop For each folder
102+
alt Recursive Mode
103+
Entity->>Entity: folder.delete_permissions_async(recursive=True)
104+
else Direct Mode
105+
Entity->>Entity: folder.delete_permissions_async(recursive=False)
106+
end
107+
Note right of Entity: Recursive calls for folders
108+
end
109+
end
110+
end
111+
end
112+
113+
Entity-->>User: Complete
114+
115+
Note over User,Logger: Key Features:
116+
Note over User,Logger: • Async operations with asyncio.gather()
117+
Note over User,Logger: • Benefactor relationship tracking
118+
Note over User,Logger: • Recursive processing capabilities
119+
Note over User,Logger: • Dry run mode for preview
120+
Note over User,Logger: • Error handling for inheritance conflicts
121+
Note over User,Logger: • Cascading permission updates
122+
```
123+
124+
### Key Components:
125+
126+
- **Entity**: The primary object (File, Folder, Project) whose permissions are being deleted
127+
- **BenefactorTracker**: Manages benefactor relationships and tracks cascading changes
128+
- **Synapse Client**: Handles API communication and logging
129+
- **Synapse API**: REST endpoints for ACL operations (`delete_entity_acl`, `get_entity_benefactor`)
130+
- **Logger**: Records operations, warnings, and debug information
131+
132+
### Flow Highlights:
133+
134+
1. **Validation Phase**: Parameter validation and client setup
135+
2. **Collection Phase**: Gathering entities for recursive operations
136+
3. **Tracking Phase**: Parallel benefactor relationship discovery
137+
4. **Preview Phase**: Dry run mode shows what would be deleted
138+
5. **Deletion Phase**: Actual ACL deletions with error handling
139+
6. **Cascading Phase**: Updates benefactor relationships for affected entities
140+
141+
3142
::: synapseclient.models.mixins.AccessControllable
143+
144+
---
145+
146+
147+
::: synapseclient.models.protocols.access_control_protocol.AccessControllableSynchronousProtocol

0 commit comments

Comments
 (0)