Skip to content

Changes

Page history
Documentation for ACL system and "ACL mediated endpoints" authored by Rob Oakes's avatar Rob Oakes 
Documentation providing information about how "tenant based data isolation" within Sonador is implemented.

* `security.index.md`: index page for security related pages within the documentation
* `security.authorization.md`: documentation describing "ACL mediated endpoints", the interaction between the ACL system within Sonador and the Orthanc Advanced Authorization plugin, the design rationale for the Sonador implementation, and implementation notes describing how the ACL mediated views were implemented inside of Orthanc
Show whitespace changes
Inline Side-by-side
security.authorization.md 0 → 100644
View page @ 0ab32568
# Resource Authorization in Sonador
The privacy and security of data is an essential priority of any healthcare data system. Data privacy is an ethical obligation and legal imperative.
Laws such as the Health Insurance Portability and Accountability Act (HIPAA) and European General Data Privacy Regulation require that medical IT companies safeguard sensitive patient information, ensuring that health data remains confidential and secure. Protecting this information is crucial to prevent unauthorized access, breaches, and misuse, which could lead to significant privacy violations. Access control mechanisms are fundamental to HIPAA and GDPR compliance, as they help regulate who can view or use protected health information (PHI), thereby minimizing risks and maintaining the integrity of healthcare data.
## Access Control (ACL) in Sonador
Sonador provides an access control (ACL) framework for resource requests to be authenticated (identify a user based on token credentials) and authorized (ensure that access to a resource has been granted). Architectural components:
* [Orthanc advanced authorization plugin](https://orthanc.uclouvain.be/book/plugins/authorization.html). When enabled, the Orthanc advanced authorization framework implements a proxy server which requires that authorization for a "resource" be provided by an external authorization service. Orthanc's documentation describes the advanced authorization plugin as "for each incoming REST request to a URL, the plugin will query an external Web service to check whether the access should be granted. If access is not granted, the HTTP status code is set to 403 (Forbidden)."
* Sonador Integration endpoints (refer to [External Web Service Specification](https://orthanc.uclouvain.be/book/plugins/authorization.html#external-web-service) for details): integration endpoints required by the advanced authorization plugin in order identify users and grant permission to resources.
* `tokens/validate`: endpoint within Sonador application to which Orthanc sends requests to ensure that a user has access to a particular resource
* `tokens/{token_type}`: endpoint capable of generating tokens to grand access to specific DICOM resources
* `tokens/decode`: extract user information and other information from a resource token
* `user/get-profile`: return the user profile linked to a given token, including a list of permissions
* Sonador (global) group policy implementation. Web application models and APIs which are used to create the integration endpoint responses. _Global policies are associated with a group instance and utilize patterns to identify resources deployed on an imaging server. Permissions associated with the policy then authorize access to specific operations associated with the matching resources._
* Orthanc (local) user/groups policy implementation. Orthanc cloud plugin models and APIs which are used to create integration endpoint responses. _Local policies can be associated with either a user or group instance, and are tied explicitly to a resource (patient, study, or series). Like global policies, permissions are used to authorize operations._
* Orthanc Cloud Plugin method overrides needed to partition resources by tenant. These "ACL mediated" endpoints are needed by Orthanc for operations (for example, `tools/find`) where the endpoint must be accessible, but the response is partitioned based on the policies that exist for the user and groups of which the user is a member. _Sonador uses group membership to provide for tenant based isolation of data._
Enforcing secure resource access in Orthanc involves two operations:
* Determining whether a user has been assigned access via an ACL policy (either global or local) and providing a grant. _Grants are generated by the "authorization API" and consumed by the [Advanced authorization plugin](https://orthanc.uclouvain.be/book/plugins/authorization.html)_
* 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 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.
These endpoints leverage the "Sonador resource cache," an extension provided by the Sonador/Orthanc cloud plugin, which enhances the access control capabilities by integrating policy-based filtering directly into the data retrieval process. As part of the broader policy system, these endpoints can execute queries across all server data when a user belongs to a group with server-wide `query` permission. In cases where it is necessary to bypass the ACL mediated endpoints and directly access the core Orthanc resources, the system allows for a pass-through by including a RapidLookup key set to true in the request, which directs the query to the native Orthanc resource instead of the plugin-managed endpoint.
This section includes details about the primary ACL mediated endpoints:
* `/tools/secure-find` (ACL mediated version of [`/tools/find`](https://orthanc.uclouvain.be/api/#tag/System/paths/~1tools~1find/post)): performs a search of content to which the user has been granted access via an ACL policy (both user and group policies are considered when filtering results).
* `/dicom-web/studies` (ACL mediated version of the DICOMweb endpoint provided by the [Orthanc DICOMweb plugin](https://www.orthanc-server.com/static.php?page=dicomweb)): provides a search interface to allow for searching for studies.
* `/dicom-web/bulk-content` (ACL mediated version of endpoint provided by [Orthanc Internal API](https://orthanc.uclouvain.be/api/#tag/System/paths/~1tools~1bulk-content/post)): retrieve the content of all DICOM patients, studies, series or instances who identifiers are requested.
in addition to details about their implementation and components.
##### `/tools/secure-find`
ACL mediated version of `/tools/find`, allowing for search of the content of the local Orthanc server.
[Request schema](https://orthanc.uclouvain.be/api/#tag/System/paths/~1tools~1find/post):
* `CaseSensitve` (boolean). Enable case-sensitive search for PN value representations (defaults to configuration option CaseSensitivePN)
* `Expand` (boolean). Also retrieve the content of the matching resources, not only their Orthanc identifiers
* `Full` (boolean). If set to true, report the DICOM tags in full format (tags indexed by their hexadecimal format, associated with their symbolic name and their value)
* `Labels` (Array of strings). List of strings specifying which labels to look for in the resources (new in Orthanc 1.12.0)
* `LabelsConstraint` (string). Constraint on the labels, can be All, Any, or None (defaults to All, new in Orthanc 1.12.0).
* `Level` (string). Level of the query (Patient, Study, Series or Instance)
* `Limit` (number). Limit the number of reported resources
* `Query` (object). Associative array containing the filter on the values of the DICOM tags.
* `RequestedTags` (Array of strings). A list of DICOM tags to include in the response (applicable only if "Expand" is set to true). The tags requested tags are returned in the 'RequestedTags' field in the response. Note that, if you are requesting tags that are not listed in the Main Dicom Tags stored in DB, building the response might be slow since Orthanc will need to access the DICOM files. If not specified, Orthanc will return all Main Dicom Tags to keep backward compatibility with Orthanc prior to 1.11.0.
* `Short` (boolean). If set to true, report the DICOM tags in hexadecimal format
* `Since` (number). Show only the resources since the provided index (in conjunction with Limit)
* `RapidLookup` (boolean). When set to true, by-pass the Sonador resource based implementation to use `tools/find` directly. _Requires that the user making the request be a member of a group with a server wide `query` permission._
Example request:
```json
{
"CaseSensitive": true,
"Expand": true,
"Full": true,
"Labels": [
"string"
],
"LabelsConstraint": "string",
"Level": "string",
"Limit": 0,
"Query": {},
"RequestedTags": [
"string"
],
"Short": true,
"Since": 0
}
```
Sample response:
```json
[
{
"ID" : "b9c08539-26f93bde-c81ab0d7-bffaf2cb-a4d0bdd0",
"IsStable" : true,
"LastUpdate" : "20180414T091528",
"MainDicomTags" : {
"InstitutionName" : "0ECJ52puWpVIjTuhnBA0um",
"ReferringPhysicianName" : "1",
"StudyDate" : "20070101",
"StudyDescription" : "Knee (R)",
"StudyID" : "1",
"StudyInstanceUID" : "1.2.840.113619.2.176.2025.1499492.7391.1171285944.390",
"StudyTime" : "120000.000000"
},
"ParentPatient" : "6816cb19-844d5aee-85245eba-28e841e6-2414fae2",
"PatientMainDicomTags" : {
"PatientID" : "ozp00SjY2xG",
"PatientName" : "KNIX"
},
"Series" : [
"20b9d0c2-97d85e07-f4dbf4d2-f09e7e6a-0c19062e",
"edbfa0a9-fa2641d7-29514b1c-45881d0b-46c374bd",
"f2635388-f01d497a-15f7c06b-ad7dba06-c4c599fe",
"4d04593b-953ced51-87e93f11-ae4cf03c-25defdcd",
"5e343c3e-3633c396-03aefde8-ba0e08c7-9c8208d3",
"8ea120d7-5057d919-837dfbcc-ccd04e0f-7f3a94aa"
],
"Type" : "Study"
}
]
```
##### `/tools/bulk-content`
ACL mediated version of `/tools/bulk-content` which allows for the bulk retrieval of resource (patient, study, series) metadata in a single call.
[Request schema](https://orthanc.uclouvain.be/api/#tag/System/paths/~1tools~1bulk-content/post):
* `Full` (boolean): If set to true, report the DICOM tags in full format (tags indexed by their hexadecimal format, associated with their symbolic name and their value)
* `Level` (string): This optional argument specifies the level of interest (can be Patient, Study, Series or Instance). Orthanc will loop over the items inside Resources, and explore upward or downward in the DICOM hierarchy in order to find the level of interest.
* `Metadata` (boolean): If set to true (default value), the metadata associated with the resources will also be retrieved.
* `Resources` (Array of strings): List of the Orthanc identifiers of the patients/studies/series/instances of interest.
* `Short` (boolean): If set to true, report the DICOM tags in hexadecimal format.
Example request:
```json
{
"Full": true,
"Level": "string",
"Metadata": true,
"Resources": [
"string"
],
"Short": true
}
```
##### `/dicom-web/studies`
ACL mediated version of the [DICOMweb Search](https://www.dicomstandard.org/using/dicomweb/query-qido-rs) endpoint.
Studies can be queried by adding DICOM tag parameters to the URL. Example URL:
```
{s}/studies?PatientID=example-patient
```
In addition to the parameters supported by the DICOMweb standard, the [Sonador/Orthanc cloud plugin](https://code.oak-tree.tech/oak-tree/medical-imaging/orthanc-sonador) endpoint for `/dicom-web/studies` provides a `Modified` parameter (date/time) which can be used to filter recently updated studies and an `OrderBy` parameter that can be used to specify the ordering of the results.
#### ACL Endpoint/View Implementation Notes
The ACL mediated endpoints within Orthanc take advantage of [Orthanc's Python plugin](https://orthanc.uclouvain.be/book/plugins/python.html) to provide a "wrapper view" which is able to sit in front of the APIs provided by Orthanc's core.
They are implemented as extensions of the [`OrthancBaseView`](https://code.oak-tree.tech/oak-tree/medical-imaging/orthanc-sonador-common/-/blob/master/web.py?ref_type=heads) class provided by the [Orthanc Sonador Plugin Common](https://code.oak-tree.tech/oak-tree/medical-imaging/orthanc-sonador-common) package and rely upon the access control framework of the Sonador/Orthanc Cloud. Mixin classes are used to identify the request user and query resources based on the permissions and policies associated with the user and the group.
Request response cycle:
* Requests are intercepted by the view instance which parses the request body to its parameters.
* The user making the request is identified by making an "introspection" request to Sonador with the authentication credentials (in the form of a `Bearer` token). The response to the the introspection request will be a copy of the user's data, including groups that she is a member of associated with the Orthanc instance. _User introspection is provided by the `UserContextMixin` available in the `sonador_orthanc.web.secure_user` module._
* The user ID and groups provided by the introspection request are used to filter resources by user and group policies so that the user is only able to retrieve resources for which she has an explicit authorization. _Resource filtering is provided by mixins provided in the `sonador_orthanc.dcmquery.auth` module._
* After resources have been filtered, the response JSON structure for each resource is aggregated by the view instance and the response is serialized and returned.
\ No newline at end of file