hazza/DSpace
1
0
Fork 0
mirror of https://github.com/DSpace/DSpace.git synced 2025-10-07 01:54:22 +00:00
Code Issues Packages Projects Releases Wiki Activity

Improve ResourcePolicy documentation.

Browse Source
This commit is contained in:
Mark H. Wood
2023-01-12 16:44:20 -05:00
committed by Mark H. Wood
parent 3aa3a945af
commit 1acdc55104
4 changed files with 104 additions and 73 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
dspace-api/src/main/java/org/dspace/authorize/ResourcePolicy.java
View File

@@ -41,9 +41,16 @@ import org.hibernate.proxy.HibernateProxyHelper;
@Entity
@Table(name = "resourcepolicy")
public class ResourcePolicy implements ReloadableEntity<Integer> {
/** This policy was set on submission, to give the submitter access. */
public static String TYPE_SUBMISSION = "TYPE_SUBMISSION";
/** This policy was set to allow access by a workflow group. */
public static String TYPE_WORKFLOW = "TYPE_WORKFLOW";
/** This policy was explicitly set on this object. */
public static String TYPE_CUSTOM = "TYPE_CUSTOM";
/** This policy was copied from the containing object's default policies. */
public static String TYPE_INHERITED = "TYPE_INHERITED";
@Id

74
dspace-api/src/main/java/org/dspace/authorize/package-info.java Normal file
View File

@@ -0,0 +1,74 @@
/**
* The contents of this file are subject to the license and copyright
* detailed in the LICENSE and NOTICE files at the root of the source
* tree and available online at
*
* http://www.dspace.org/license/
*/
/**
* Represents permissions for access to DSpace content.
*
* <h2>Philosophy</h2>
* DSpace's authorization system follows the classical "police state"
* philosophy of security - the user can do nothing, unless it is
* specifically allowed. Those permissions are spelled out with
* {@link ResourcePolicy} objects, stored in the {@code resourcepolicy} table
* in the database.
*
* <h2>Policies are attached to Content</h2>
* Resource Policies get assigned to all of the content objects in
* DSpace - collections, communities, items, bundles, and bitstreams.
* (Currently they are not attached to non-content objects such as
* {@code EPerson} or {@code Group}. But they could be, hence the name
* {@code ResourcePolicy} instead of {@code ContentPolicy}.)
*
* <h2>Policies are tuples</h2>
* Authorization is based on evaluating the tuple of (object, action, actor),
* such as (ITEM, READ, EPerson John Smith) to check if the {@code EPerson}
* "John Smith" can read an item. {@code ResourcePolicy} objects are pretty
* simple, describing a single instance of (object, action, actor). If multiple
* actors are desired, such as groups 10, 11, and 12 are allowed to READ Item
* 13, you simply create a {@code ResourcePolicy} for each group.
*
* <h2>Built-in groups</h2>
* The install process should create two built-in groups - {@code Anonymous} for
* anonymous/public access, and {@code Administrators} for administrators.
* Group {@code Anonymous} allows anyone access, even if not authenticated.
* Group {@code Administrators}' members have super-user rights,
* and are allowed to do any action to any object.
*
* <h2>Policy types
* Policies have a "type" used to distinguish policies which are applied for
* specific purposes.
* <dl>
* <dt>CUSTOM</dt>
* <dd>These are created and assigned explicitly by users.</dd>
* <dt>INHERITED</dt>
* <dd>These are copied from a containing object's default policies.</dd>
* <dt>SUBMISSION</dt>
* <dd>These are applied during submission to give the submitter access while
* composing a submission.</dd>
* <dt>WORKFLOW</dt>
* <dd>These are automatically applied during workflow, to give curators access
* to submissions in their curation queues. They usually have an
* automatically-created workflow group as the actor.</dd>
*
* <h2>Start and End dates</h2>
* A policy may have a start date and/or an end date. The policy is considered
* not valid before the start date or after the end date. No date means do not
* apply the related test. For example, embargo until a given date can be
* expressed by a READ policy with a given start date, and a limited-time offer
* by a READ policy with a given end date.
*
* <h2>Unused ResourcePolicy attributes</h2>
* {@code ResourcePolicy} has a few attributes that are currently unused,
* but are included with the intent that they will be used someday.
* One is the {@code EPerson} - policies could apply to only a single EPerson,
* but for ease of administration currently a Group is the recommended unit to
* use to describe the actor.
*
* @author dstuve
* @author mwood
*/
package org.dspace.authorize;

68
dspace-api/src/main/java/org/dspace/authorize/package.html
View File

@@ -1,68 +0,0 @@
<!--
The contents of this file are subject to the license and copyright
detailed in the LICENSE and NOTICE files at the root of the source
tree and available online at
http://www.dspace.org/license/
-->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!--
Author: dstuve
Version: $Id$
Date: $Date$
-->
</head>
<body bgcolor="white">
<p>Handles permissions for DSpace content.
</p>
<p><strong>Philosophy</strong><br>
DSpace's authorization system follows the classical "police state"
philosophy of security - the user can do nothing, unless it is
specifically allowed. Those permissions are spelled out with
ResourcePolicy objects, stored in the resourcepolicy table in the
database.
</p>
<h2>Policies are attached to Content</h2>
<p><strong>Policies are attached to Content</strong><br>
Resource Policies get assigned to all of the content objects in
DSpace - collections, communities, items, bundles, and bitstreams.
(Currently they are not attached to non-content objects such as EPerson
or Group. But they could be, hence the name ResourcePolicy instead of
ContentPolicy.)
</p>
<h2>Policies are tuples</h2>
Authorization is based on evaluating the tuple of (object, action, who),
such as (ITEM, READ, EPerson John Smith) to check if the EPerson "John Smith"
can read an item. ResourcePolicy objects are pretty simple, describing a single instance of
(object, action, who). If multiple who's are desired, such as Groups 10, 11, and
12 are allowed to READ Item 13, you simply create a ResourcePolicy for each
group.
</p>
<h2>Special Groups</h2>
The install process should create two special groups - group 0, for
anonymous/public access, and group 1 for administrators.
Group 0 (public/anonymous) allows anyone access, even if they are not
authenticated. Group 1's (admin) members have super-user rights, and
are allowed to do any action to any object.
</p>
<h2>Unused ResourcePolicy attributes </h2>
ResourcePolicies have a few attributes that are currently unused,
but are included with the intent that they will be used someday.
One is start and end dates, for when policies will be active, so that
permissions for content can change over time. The other is the EPerson -
policies could apply to only a single EPerson, but for ease of
administration currently a Group is the recommended unit to use to
describe 'who'.
</p>
</body>
</html>

28
dspace-api/src/main/java/org/dspace/authorize/service/ResourcePolicyService.java
View File

@@ -53,12 +53,19 @@ public interface ResourcePolicyService extends DSpaceCRUDService<ResourcePolicy>
throws SQLException;
/**
* Look for ResourcePolicies by DSpaceObject, Group, and action, ignoring IDs with a specific PolicyID.
* This method can be used to detect duplicate ResourcePolicies.
* Look for ResourcePolicies by DSpaceObject, Group, and action, ignoring
* IDs with a specific PolicyID. This method can be used to detect duplicate
* ResourcePolicies.
*
* @param notPolicyID ResourcePolicies with this ID will be ignored while looking out for equal ResourcePolicies.
* @return List of resource policies for the same DSpaceObject, group and action but other policyID.
* @throws SQLException
* @param context current DSpace session.
* @param dso find policies for this object.
* @param group find policies referring to this group.
* @param action find policies for this action.
* @param notPolicyID ResourcePolicies with this ID will be ignored while
* looking out for equal ResourcePolicies.
* @return List of resource policies for the same DSpaceObject, group and
* action but other policyID.
* @throws SQLException passed through.
*/
public List<ResourcePolicy> findByTypeGroupActionExceptId(Context context, DSpaceObject dso, Group group,
int action, int notPolicyID)
@@ -68,6 +75,16 @@ public interface ResourcePolicyService extends DSpaceCRUDService<ResourcePolicy>
public boolean isDateValid(ResourcePolicy resourcePolicy);
/**
* Create and persist a copy of a given ResourcePolicy, with an empty
* dSpaceObject field.
*
* @param context current DSpace session.
* @param resourcePolicy the policy to be copied.
* @return the copy.
* @throws SQLException passed through.
* @throws AuthorizeException passed through.
*/
public ResourcePolicy clone(Context context, ResourcePolicy resourcePolicy) throws SQLException, AuthorizeException;
public void removeAllPolicies(Context c, DSpaceObject o) throws SQLException, AuthorizeException;
@@ -117,6 +134,7 @@ public interface ResourcePolicyService extends DSpaceCRUDService<ResourcePolicy>
* @param ePerson ePerson whose policies want to find
* @param offset the position of the first result to return
* @param limit paging limit
* @return some of the policies referring to {@code ePerson}.
* @throws SQLException if database error
*/
public List<ResourcePolicy> findByEPerson(Context context, EPerson ePerson, int offset, int limit)