Skip to content

Changes

Page history
Sonador Viewer: Frontend architcture, code overview, API organization authored by Rob Oakes's avatar Rob Oakes 
Frontend documentation for the Sonador Viewer. Describes organization, components, and function.

* Architecture
  * Dependencies and what role they play in the application.
  * Code and repository organization.
  * Core packages and extensions
* Anatomy of a Sonador extension
* VTK extension and tools
* Integration with Cornerstone3D and future development roadmap

Also includes details on the ACL system in Sonador: URL structure, Python examples, and link to engineering notebook.
Show whitespace changes
Inline Side-by-side
security.authorization.md
View page @ eaa095f6
...@@ -23,6 +23,160 @@ Enforcing secure resource access in Orthanc involves two operations: ...@@ -23,6 +23,160 @@ Enforcing secure resource access in Orthanc involves two operations:
* Providing "ACL mediated endpoints" that allow for users to retrieve and search lists of resources to which they have been granted access. _ACL mediated resourcs are endpoints such as `/tools/find`, `/dicom-web/studies/`, and `/tools/bulk-content` that are used to retrieve many resource instances at a time. They are used by integrated systems to search data to which the user has access and perform operations._ * Providing "ACL mediated endpoints" that allow for users to retrieve and search lists of resources to which they have been granted access. _ACL mediated resourcs are endpoints such as `/tools/find`, `/dicom-web/studies/`, and `/tools/bulk-content` that are used to retrieve many resource instances at a time. They are used by integrated systems to search data to which the user has access and perform operations._
### ACL Policies in Sonador
Access control policies in Sonador define which users or groups have permission to view, interact with, or modify sensitive medical data, ensuring the confidentiality, security, and regulatory compliance (e.g., HIPAA and GDPR) of patient information. In simple terms, these policies determine who can see or change what data, making them a critical element in secure data management.
#### How Access Control Policies Work
Sonador’s access control system allows administrators and developers to precisely define permissions for accessing resources such as patients, specific imaging studies, or series of images. Permissions are explicitly granted by creating policies assigned either to individual users or groups of users.
Policies can be defined at two levels:
* **Global Policies (pattern based)**:
- API located within the Sonador web application.
- Use regular expression patterns to broadly define access across many resources (patients, studies, series).
- Suitable for granting wide-ranging permissions across an entire imaging database or subsets defined by pattern matching.
- Use of global policies is generally discouraged because it may unintentionally grant overly broad permissions, reducing the precision of resource management. _Evaluation of global patterns is also more computationally intensive, as it requries multiple requests between Sonador and Orthanc to resolve._
* **Local Policies (resource specific)**:
- API implemented directly in Orthanc through the Orthanc cloud plugin, allowing for direct relations between the policy and resource tables. _Local policies provide the cross-table lookup that enables ACL mediated endpoints (refer below for additional detail)._
- Explicitly linked to specific resources (patients, studies, series).
- Provide fine-grained, highly controlled permissions to ensure tight control and specificity, significantly reducing the risk of unintended access.
#### API Structure for Managing Access Control Policies
The Sonador platform provides two distinct APIs to support the creation and management of these policies:
* **Sonador (Global) Access Control API**:
- Integrated into the [Sonador web application](https://code.oak-tree.tech/oak-tree/medical-imaging/sonador).
- Policies are managed using URL patterns and resource matching.
- Follows the conventional REST API patterns found within [Sonador’s broader ecosystem](https://code.oak-tree.tech/django-apps/guru/-/wikis/dev.data-models).
- API requests use a JSON-based schema with group IDs or user IDs, resource patterns, and associated permissions.
* **Orthanc (Local) Access Control API**:
- Integrated directly within Orthanc through the [cloud plugin](https://code.oak-tree.tech/oak-tree/medical-imaging/orthanc-sonador).
- Policies are tied specifically to Orthanc resources (Patients, Studies, Series) identified by unique identifiers (UIDs).
- Two separate endpoint structures manage resource policies:
+ A management endpoint for creating new policies or retrieving existing policy lists.
+ A REST endpoint for fetching, updating, or deleting specific policies.
- The Orthanc API endpoints clearly differentiate between user- and group-level policies.
#### Example API Endpoints (Orthanc Local Policies)
Study ACL management:
* Management endpoint `POST/GET`: `study/{StudyInstanceUID}/acl/{user|group}`
- `POST`: create a new ACL policy instance
- `GET`: retrieve all defined ACL policies for the resource
* REST endpoint `GET/PUT/DELETE`: `study/{StudyInstanceUID}/acl/{user|group}/{PolicyUUID}`
- `GET`: retrieve details for the policy instance
- `PUT`: update details for the policy instance
- `DELETE`: remove/revoke the policy
Series ACL management:
* Management endpoint `POST/GET`: `series/{SeriesInstanceUID}/acl/{user|group}`
* REST endpoint `GET/PUT/DELETE`: `series/{SeriesInstanceUID}/acl/{user|group}/{PolicyUUID}`
**Note**: User and Group policies share nearly identical request/response structures, differing only in that user policies use a User key (containing the Sonador user UID), whereas group policies use a Group key (with the group UID).
#### Guidance for Developers and Users
When creating integrations or writing code against these APIs, consider:
* **Precision**: Always prefer local, resource-specific policies for better security. Use global policies sparingly and cautiously.
* **API Compatibility**: The global and local APIs use slightly different URL structures and JSON schemas due to their placement within different application contexts (Sonador web app vs. Orthanc cloud plugin). Pay close attention to these syntactic differences when building integrations or automation scripts.
* **UID Management**: User and group identifiers (UIDs) in Sonador are integers. Proper management of these identifiers is critical when assigning permissions and defining access control policies programmatically.
This approach ensures accurate, secure, and compliant data-sharing scenarios tailored to both organizational needs and legal standards.
**Resource requests are processed by Sonador and take into account first global policies and then local policies.** Requests are sent from Orthanc to the Sonador authorization API (an implementation of the Orthanc advanced authorization service API) when a user attempts to request a resource from Orthanc. If a policy is found which matches the requested resource, Sonador grants access; if not the request is denied and Orthanc will return a 403 error.
#### API Structure
**Global policies** are associated with an imaging server and group and are sent to the Sonador web application. Requests have the following general schema:
```json
{
"server": "{server-id}",
"group": 1,
"resource": "*",
"query": true,
"upload": true,
"modify": true,
"remove": true,
"comment_edit": true,
"comment_view": true,
"acl": true,
}
```
* `server` (str): server ID of the Orthanc instance
* `group` (int): group which the ACL policy should be associated with
* `resource` (str): resources with which the policy should be associated. Example resource definitions:
- global resource access: `*`
- patient: `patient={resource-uid]` (also provides access to child study and series)
- study: `study={resource-uid}` (also provides access to child series)
- series: `series={resource-uid}`
* `query` (bool): allows for query of imaging resources on a server
* `upload` (bool): allows for upload of medical data to the server
* `view` (bool): allows for the user to download/view medical imaging data
* `modify` (bool): allows for the user to change the medical imaging data
* `remove` (bool): provides permission to allow the user to remove the resource
* `comment_edit` (bool): provides permission for the user to add/remove comments for a series
* `comment_view` (bool): provides permisson for the user to view comments for a series (works in tandem with manage_comments, when both permissions are present manage_comments will take precdence)
* `acl` (bool): provides permission for the user to create or modify ACL policies
* `duration` (int): amount of time in seconds that a "grant" is allowed for resources which match the policy
**Local policies** are associated with a group and a specific resource and are sent to Orthanc. _To create or modify ACL policies, a user must have an `acl` permission for the server which matches the resource._ Their request structure for local policies is similar to that of global policies, with the exception that it uses camel-casing for key names. Example:
```json
{
"View": true,
"Modify": true,
"Remove": true,
"ACL": true,
"CommentEdit": true,
"CommentView": true,
}
```
##### Managing Resources via the Sonador IO Client
Resources can be managed using the [Sonador IO client library](https://code.oak-tree.tech/oak-tree/medical-imaging/sonador-client).
**Global Policies.** ACL methods are available via the `sonador.servers.SonadorImagingServer` class. The code below shows the creation of a group access control policy for a test group:
```python
# Create (or retrieve if it already exists) a test group
testgroup01 = iserver.server.admin_create_group({ 'name': 'ACL Test' })
# Create a global ACL policy for members of the test group
testacl01 = iserver.admin_create_acl(testgroup01, {
'resource': '*', 'view': True, 'duration': 1
})
```
Global resource policies can be scoped to more specifically match a target. The example in the listing below shows how to generate a policy that matches an Orthanc series:
```python
# Create a policy for the test group specific to example 1
testacl01_global = iserver.admin_create_acl(testgroup01, {
'resource': 'series=%s' % example_sx01.pk, 'view': True, 'duration': 1
})
```
`example_sx01` in the code above is a reference to an Orthanc imaging series.
**Local Policies.** Methods for managing local ACL policies can be accessed from resource instances retrieved from Sonador. The example below shows how to create a user policy for a series:
```python
# Create a policy for a test user
testacl01_local = test01_sx.create_user_acl(testuser01, {
'View': True, 'Modify': False, 'Remove': False, 'ACL': False,
'CommentEdit': True, 'CommentView': True
})
```
**Notes**: more information about access control policies, along with examples of their management can be found in the ["Managing Resource Access"](https://code.oak-tree.tech/oak-tree/medical-imaging/sonador-examples/-/blob/master/technical-reference/sonador-auth.resource-acl.ipynb?ref_type=heads) Jupyter notebook in the [Sonador Technical reference repository](https://code.oak-tree.tech/oak-tree/medical-imaging/sonador-examples/-/tree/master/technical-reference?ref_type=heads).
#### Managing ACL Policies (OHIF Interface)
The Sonador viewer provides an interface which can be used to manage ACL policies, available from the study explorer.
<img src="https://www.oak-tree.tech/content/api/images/1171/large" alt="ACL management interface in the Sonador viewer" align="right" />
### ACL Mediated Endpoints ### ACL Mediated Endpoints
ACL mediated endpoints in Sonador and Orthanc are designed to filter and control access to data based on user and group policies defined on the server, ensuring that users only see the data they are authorized to access. ACL mediated endpoints in Sonador and Orthanc are designed to filter and control access to data based on user and group policies defined on the server, ensuring that users only see the data they are authorized to access.
......