Configuration of Study Permissions (Role Based Access Control)

h2. Study Permission functionalities

A "StudyPermission" entity, with a N:1 relation ship to the Study entity, with a "role", an an "action" attribute.
When an association is accepted, one or several roles are associated with that association, based on the identity of the association initiator: In the simplest version, it may be a lookup in the existing roles table with the Called AET as user_id. If the Association initiator supports negotiation of the user identity in the A-Associate RQ, instead of the AET, the user id can be used for the lookup. And there will be an extension point, to get the associated roles to that association initator from other sources than the roles TABLE.
When a Study is created on receive of its first object, permissions will be created and linked to this Study according a configurable policy, which may consider not only the roles associated with the STORE SCU as described above, but also attributes of the object, in particular request attributes (e.g. Requesting Service) fetched from a specified MWL SCP and merged into the received object.
Consideration of Storage or Retrieve permissions is even simpler, because the operation will fail if the association initiator has not assigned a role with the permission to perform the requested operation.
For retrieve you may have to distinguish between a 'read' permission for the Storage SCP acting as Move Destination and a 'retrieve' permission for the Move SCU.
Permissions are definded by the relationship from StudyIUID to role and actions.

Possible Actions are:

Q (Query) -- Query Study
R (Read) -- Retrieve Study
E (Export) -- Export Study to XDS/TCE
A (Append) -- Append data to study
U (Updated) -- Update Attributes in Webinterface
D (Delete) -- Delete Study in Webinterface

h2. _Services involved_

* DicomSecurityService:
DICOM Security Service. Performs JAAS login with user information provided in the Association Request or AE configuration for the calling AE and make returned information about user roles available for invoked DICOM services.

* StudyPermissionService
** Provide functionalities to grant/revoke study access permissions to particular roles on receive of HL7 messages (hl7-permission.xsl), MPPS N-CREATE messages (Performed Station AET is passed as XSLT parameter 'calling' to mpps-permission.xsl), Series Stored events (Calling AET is passed as XSLT parameter 'calling' to series-permission.xsl) or by direct user interaction via WebInterface.
** Desired way to set study permissions has to be enabled, e.g.:
[Study Permission Service#UpdateOnSeriesStored] = {{true}}

* QueryRetrieve SCP
** Query
UnrestrictedQueryPermissionsToAETitles
AE Titles of C-FIND SCUs with Query Permissions on all archived Studies, independent of Study Permissions to roles of the user associated to the active association.
Separate multiple values by
(backslash).
ANY = Disable restrication of queries according granted Study Permissions.
** Export and Read
Check Export and Read Permissions on requested Studies for the Move Requestor and the Move Destination, if their AE Titles are not listed in UnrestrictedExportPermissionsToAETitles and UnrestrictedReadPermissionsToAETitles.
** Retrieve will fail with Cxxx, "Unable to Process", if no user identification is associated with the Move Requestor and the Move Destination or the user has no permission to export or read the requested study.
Error Status, Error Message
CE10, Missing user identification of Move originator
CE12, Missing or invalid user identification of Move destination
CE20, Move destination has no permission to read Study
CE22, Move originator has no permission to export Study
** The PACS "MASTER_AET" should be set to have unrestricted permissions:
[Query Retrieve SCP#UnrestrictedReadPermissionsToAETitles] = {{MASTER_AET}}
[Query Retrieve SCP#UnrestrictedQueryPermissionsToAETitles] = {{MASTER_AET}}
[Query Retrieve SCP#UnrestrictedExportPermissionsToAETitles] = {{MASTER_AET}}

* StoreSCP
** Restrict storage operation according Study Append Permissions granted to roles of the user associated with the Storage SCU, if its AE Title is not listed in UnrestrictedAppendPermissionsToAETitles.
If the archive already contains objects of the same study as the received object belongs, storage will fail with Cxxx Error: Cannot understand, if no user identification is associated with the Storage Requestor or if the user has no permission to store additional object to an already existing study.
** Error Status Error message
CE10 Missing user identification for appending existing Study
** CE24 No permission to append existing Study
* WADO
Access according Study Read Permissions granted to roles of authentified user. Edit servlet Parameters to activate Read Permissions for access via WADO:
{code:xml}
<!--Enable/Disable StudyPermissionCheck for WADO retrieve true: -->
<!-- restrict WADO retrieve of objects according Study Read permission of remote user. -->
<!-- denied access if no remote user information is associated with the request false: no restriction. -->
<init-param>
<param-name>enableStudyPermissionCheck</param-name>
<param-value>false</param-value>
</init-param>
<!-- Disable StudyPermissionCheck for dedicated user(s). -->
<!-- List of users (seperated by ',') for which Study Read permissions are not checked on WADO retrieve, -->
<!-- even if enableStudyPermissionCheck=true. default: admin -->
<init-param>
<param-name>disableStudyPermissionCheckForUser</param-name>
<param-value>admin</param-value>
</init-param>
{code}
* AE Management
User ID and Password attribute are configurable for AET's which do not support user identification
* WebInterface
** Configure the Web Interface for usage of study permissions:
*** Enable Study Permission for WebInterface
Query, Edit and Delete restrictions are anabled by setting the following parameter in ../server/default/deploy/dcm4chee-web.war/WEB-INF/web.xml (has to be extracted for editing):
{code:xml}
<init-param>
<param-name>enableStudyPermissionCheck</param-name>
<param-value>false</param-value>
</init-param>
{code}
*** It is als possible to disable StudyPermissionCheck for dedicated user(s) (seperated by ',') that should see all studies (e.g. to configure Study Permissions Roles.

*** Grant/Revoke Study Permission
Users have to be assigned to one of the following roles to be able to grant/revoke study permissions:
GrantPrivileg -- Users of this role are allowed to grant/revoke study sermissions for ALL studies in the archive
GrantOwnPrivileg -- Users of this role are allowed to grant/revoke study permissions for those studies they have already got read permission
*** If user authentificationis managed by the PACS Database these roles have to be enabled in.../dcm4chee-web/dcm4chee-webroles-cfg.xml.
{code:xml}
<role name="client1" type="StudyPermission" descr="Role for client 1 (Radiology)"/>
<role name="client2" type="StudyPermission" descr="role for client 2 (Neurosurgery)"/>
{code}

series-permission.xsl sample:

{code:xml}
<!-- Sample configuration for grant/revoke Study Permissions on Series Stored event -->
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:output method="xml"/>
<xsl:param name="calling" select="'SAMPLE_MOD'"/>
<xsl:template match="/dataset">
<permissions>
<xsl:variable name="studyUID" select="attr[@tag='0020000D']" />
<xsl:variable name="seriesMOD" select="attr[@tag='00080060']" />
<xsl:variable name="patIssuer" select="attr[@tag='00100021']" />
<xsl:choose>
<!--
Configuration for CT stored in client2 - Neurosurgery
-->
<xsl:when test="$seriesMOD='CT' and not(contains(@patIssuer,'DCM4CHEE'))">
<!-- grant Query, Read and Append permission on Study to client2 in special case -->
<grant role="client2" action="Q,R,A" suid="{attr[@tag='0020000D']}"/>
</xsl:when>
<!--
Configuration for CT stored in client1 - Radiology (having ISSUER set to DCM4CHEE)
-->
<xsl:when test="$seriesMOD='CT' and contains(@patIssuer,'DCM4CHEE')">
<!-- grant Query, Read and Append permission on Study to client2 in special case -->
<grant role="client1" action="Q,R,A" suid="{attr[@tag='0020000D']}"/>
</xsl:when>
<!--
all other Modalities stored client1 - Radiology (having ISSUER set to DCM4CHEE)
-->
<xsl:otherwise>
<!-- grant Query, Read and Append permission on Study to client1 per default -->
<grant role="client1" action="Q,R,A" suid="{attr[@tag='0020000D']}"/>
</xsl:otherwise>
</xsl:choose>
{code}
PITFALLS:
Make sure that your WebViewer is able to show files after enabling the Security Features.