This Work Is Licensed Under a Creative Commons Attribution-Noncommercial-Sharealike 3.0

ANU Data Commons

Permissions Guide

This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Australia License.

Contents

Overview

License

Acknowledgement

Vocabulary

Architecture

Table Explanations

User Tables

users

user_registered

authorities

ACL Permission tables

acl_sid

acl_class

acl_object_identity

acl_entry

Access Control Lists – ACL

Insert Values

Create a Domain

Create a Group

Assign Permissions to Group for User or Role

Overview

This document explains the permissions model adopted by the ANU Data Commons software. This document is intended to supplement but not replace the Spring Security documentation.

The ANU Data Commons uses the Spring Security Framework 3.0.5 as its underlying authentication and authorization system. Documentation for the framework can be found at: . To provide for the desired functionality of Data Commons some Spring Security classes have been extended, these classes are contained in the package au.edu.anu.datacommons.security and its sub-packages. The ANU Data Commons uses a combination of users, their authorities and Access Control List permissions to grant or deny access (i.e. A user, what type of user, and whether they have permission to view an object).

License

Use of ANU Data Commons is governed by the GNU GPL3 license.

Acknowledgement

This project is supported by the Australian National Data Service (ANDS). ANDS is supported by the Australian Government through the National Collaborative Research Infrastructure Strategy Program and the Education Investment Fund (EIF) Super Science Initiative.

Vocabulary

ACL – Access Control List

Architecture

Table Explanations

User Tables

The user tables hold information about the users and their authorities.

users

The users table provides base information about users that have been created.

‘id’ – This is an automatically generated number

‘username’ – The username for the logged in user. For registered users this will be their email address, for users that log in via CAS this will be their university id.

‘password’ – For registered users the password is encrypted. For non-registered users the password shown in the database is the same as the username, however the actual password will be dependent on their authentication method.

‘enabled’ – Indicates if the user is enabled.

‘user_type’ – Indicator field for which type of user the person is. The values are defined in the ‘user_type’ table.

user_registered

The user_registered table contains information about registered users such as their name, institution, phone number, and address.

authorities

This table delegates authorities to users. It helps to define what sort of role the user belongs to. Current roles are “ROLE_REGISTERED”, “ROLE_ANU_USER”, and “ROLE_ADMIN”.

ACL Permission tables

There are four ACL tables (acl_sid, acl_entry, acl_object_class, acl_class). Each of these perform a different task. The acl_sid table essentially maps to

acl_sid

The acl_sid table assigns an id to the user or authority for use in the acl tables. It has the following columns in the table:

‘id’ – This is an automatically generated number and is used as ‘sid’ in the other acl tables.

‘principal’ – indicates whether the entity is a user or an authority. It is ‘true’ if it is a user.

acl_class

The acl_class table maps an id to a java class type. It has the following columns:

‘id’ – An automatically generated number

‘class’ – This relates to an entity object in java e.g. ‘au.edu.anu.datacommons.data.db.model.Groups’. The entity object may then relate to another table in the database. Currently we have Domains, Groups, and FedoraObjects within this table.

acl_object_identity

The acl_object_identity table contains information about objects so that the access permissions of an object can be mapped in another table to a user. It essentially maps the objects from their appropriate table, the type of object, and its parent object.

‘id’ – An automatically generated number

‘object_id_class’ – The class for the object, this maps to the acl_class table

‘object_id_identity’ – The object for which the row relates. It is the id contained within the associated class table. For example if the ‘object_id_class’ was 2, as the associated row in ‘acl_class’ relates to the ‘Groups’ class and then the ‘groups’ table we need to look at the ‘groups’ table and find the id for that table. The value of this id is what is entered into this column.

‘owner_sid’ – Indicates the sid of who owns the record. In reality this indicates who is able to change the ‘parent_object’ of the row unless the user has administration permissions on the object.

‘parent_object’ – This indicates a parent object for the current row. This id relates to another row in the ‘acl_object_identity’ table that is considered as the parent. Parent objects mean that there can be cascading permissions, so that a permission can be set at a higher level (e.g. groups) that is available at a lower permission (e.g fedora object).

‘entries_inheriting’ – Indicates whether entries inherit permissions from parent objects.

acl_entry

The acl_entry table assigns permissions for objects to users.

‘id’ – Automatically generated id

‘acl_object_identity’ – This is the id of the object associated row in the ‘acl_object_identity’ table.

‘ace_order’ – This determines the order in which permissions are checked for the object. For the purposes of Data Commons this does not matter and simply needs to be a unique sequence number for the ‘acl_object_identity’.

‘sid’ – The sid of the user/authority for which the permission is assigned, this relates to the ‘acl_sid’ table.

‘mask’ – The mask id of the permission level. The default ACL permissions are 1 – ‘READ’, 2 – ‘WRITE’, 4 – ‘CREATE’, 8 – ‘DELETE’, 16 – ‘ADMINISTRATION’. At the time of writing this document the following permissions are also used: 32 – ‘REVIEW’, 64 – ‘PUBLISH’, 128 – ‘MASS PUBLISH’, 256 – ‘ASSIGN PERMISSIONS’.

‘granting’ – Indicates whether the access level is granted or denied to the user.

‘audit_success’ – Indicates whether to log successful requestsfor access.

‘audit_failure’ – Indicates whether to log failed requests for access.

Access Control Lists – ACL

ACLs are an object level form of permission control. They allow the granting/denial of access to specific objects. In the Spring Security ACL implementation permissions are able to inherit from other objects assuming that an association has been defined to the object and the entries_inheriting flag has been set in the acl_object_identity table (i.e. a child object can inherit permissions from a parent object when the entries_inheriting flag is set to true).

Permissions can be either assigned for users or granted authorities. Both these object types can be placed into the acl_sid table. Whether the row in the acl_sid table is a user or an authority is defined by the principal field (‘1’ indicates the acl is for a user, ‘0’ indicates it is a granted authority). Either the username (defined in the users table) or the authority name (i.e. the authority that goes into the authorities table).

In our instance we have three types of objects (i.e. tables) for which we defined ACLs; domains, groups, and fedora_object. For each of these objects we have an appropriate row in the acl_class table that assigns an identifier used to populate the object_id_classfield of the acl_object_identity table. The currently assigned classes and identifiers are 1 for domains, 2 for groups, and 3 for fedora objects.

The identifier found in acl_class is combined with the identifier from the object table to create the appropriate row in the acl_object_identity table. The actual permissions for a user/authority are defined in the acl_entrytable. What permission has been assigned can be found in the mask field (see maskfor details).

Insert Values

Create a Domain

-- insert the domain

insert into domains (domain_name) values ($DOMAIN_NAME);

-- get the domain id

select domains.id from domains where domain_name = ‘$DOMAIN_NAME’;

-- get the aclsid id for the admin role

select id from acl_sid where username = ‘ROLE_ADMIN’;

-- insert a row into the acl_object_identity table

insert into acl_object_identity (object_id_class, object_id_identity, owner_sid, parent_object, entries_inheriting) values (1, $DOMAIN_ID, $ACL_SID_ID, null, ‘1’);

-- retrieve the id of the row just inserted

select acl_object_identity.id from acl_object_identity where object_id_class = 1 and object_id_identity = $DOMAIN_ID;

-- insert rows into the acl_entry table assigning permissions

-- to the administrators role

insert into acl_entry (acl_object_identity, ace_order, sid, mask, granting, audit_success, audit_failure) values ($DOMAIN_ACL_OBJECT_ID, 0, $ACL_SID, 1, ‘1’, ‘0’,’0’);

insert into acl_entry (acl_object_identity, ace_order, sid, mask, granting, audit_success, audit_failure) values ($DOMAIN_ACL_OBJECT_ID, 1, $ACL_SID, 2, ‘1’, ‘0’,’0’);

insert into acl_entry (acl_object_identity, ace_order, sid, mask, granting, audit_success, audit_failure) values ($DOMAIN_ACL_OBJECT_ID, 2, $ACL_SID, 16, ‘1’, ‘0’,’0’);

insert into acl_entry (acl_object_identity, ace_order, sid, mask, granting, audit_success, audit_failure) values ($DOMAIN_ACL_OBJECT_ID, 3, $ACL_SID, 32, ‘1’, ‘0’,’0’);

insert into acl_entry (acl_object_identity, ace_order, sid, mask, granting, audit_success, audit_failure) values ($DOMAIN_ACL_OBJECT_ID, 4, $ACL_SID, 64, ‘1’, ‘0’,’0’);

Create a Group

-- create the group

insert into groups (group_name) values ($GROUP_NAME);

-- get the id of the created group

select groups.id from groups where group_name = $GROUP_NAME;

-- get the aclsid id for the admin role

select id from acl_sid where username = ‘ROLE_ADMIN’;

-- get the id of the domain you wish to associate the group with

select domains.id from domains where domain_name = ‘$DOMAIN_NAME’;

-- get the acl_object_identity identifier for the domain

select acl_object_identity.id from acl_object_identity where object_id_class = 1 and object_id_identity = $DOMAIN_ID;

-- insert the group into the acl_object_identity table

insert into acl_object_identity (object_id_class, object_id_identity, owner_sid, parent_object, entries_inheriting) values (1, $GROUP_ID, $ACL_SID_ID, $DOMAIN_ACL_OBJECT_ID, ‘1’);

Assign Permissions to Group for User or Role

-- get the id of the group

select groups.id from groups where group_name = $GROUP_NAME;

-- get acl_object_identity identifier for the group

select acl_object_identity.id from acl_object_identity where object_id_class = 1 and object_id_identity = $GROUP_ID;

-- get the id of the user/role

select acl_sid.id from acl_sid where sid = $USERNAME;

-- assign the permissions

insert into acl_entry (acl_object_identity, ace_order, sid, mask, granting, audit_success, audit_failure) values ($DOMAIN_ACL_OBJECT_ID, 0, $ACL_SID, $MASK, ‘1’, ‘0’,’0’);

Page 1 of 7