Security Tutorial 01: Initial setup

[fleXive] allows the definition of scripts which are executed once during the initial setup. For this application a Groovy script has been defined to set up user groups, user accounts, the data structures for the announcements and content security.

Run-once script asubmission001.groovy

import com.flexive.shared.scripting.groovy.*
import com.flexive.shared.value.*
import com.flexive.shared.structure.*
import com.flexive.shared.EJBLookup
import com.flexive.shared.FxContext;
import com.flexive.shared.interfaces.AccountEngine;
import com.flexive.shared.security.ACL;
import com.flexive.shared.security.UserGroup;
import com.flexive.shared.security.AccountEdit
import com.flexive.shared.interfaces.ACLEngine
import com.flexive.shared.interfaces.UserGroupEngine;
import com.flexive.shared.CacheAdmin;
import com.flexive.shared.structure.FxEnvironment;

// Create needed types, users, usergroups and acls if not already present
if (!CacheAdmin.getEnvironment().typeExists("announcementEntry")) {
    // Get engines
    UserGroupEngine ugEng = EJBLookup.getUserGroupEngine();
    AccountEngine accEng= EJBLookup.getAccountEngine();
    ACLEngine aclEng = EJBLookup.getAclEngine()

    // Create [fleXive] data structure announcementEntry

    // Create a type ACL used for all instances of our data structure
    long announcementTypeACLId = aclEng.create(  //(1)
            "Announcement Type ACL",
            new FxString("Announcement Type ACL"),
            FxContext.get().getTicket().getMandatorId(),
            "#CC9900",
            "Announcement Type ACL",
            ACL.Category.STRUCTURE
    )

    new GroovyTypeBuilder().announcementEntry(  //(2)
            description: new FxString(true, "Announcement"),
            useTypePermissions: true, //(3)
            useInstancePermissions: true) //(4)
            acl: CacheAdmin.getEnvironment().getACL(announcementTypeACLId), //(5)
            {
                caption(assignment: "ROOT/CAPTION", multiplicity: FxMultiplicity.MULT_1_1) //(6)
                publishDate(dataType: FxDataType.Date, multiplicity: FxMultiplicity.MULT_0_1, description: new FxString(true, "Publish Date")) //(7)
                publishURL(multiplicity: FxMultiplicity.MULT_0_1, description: new FxString(true, "Publish URL")) //(8)
                announcementText(FxDataType.Text, multiplicity: FxMultiplicity.MULT_1_1, description: new FxString(true, "Announcement Text"), multiline: true) //(9)
            }

    // Create user groups
    long uGroupEditors = ugEng.create("Editors", "#CC9900", FxContext.get().getTicket().getMandatorId()) //(10)
    long uGroupVisitors = ugEng.create("Visitors", "#CC9900", FxContext.get().getTicket().getMandatorId())
    
    // Create user accounts ...
    AccountEdit editorAccount = new AccountEdit() //(11)
    AccountEdit visitorAccount = new AccountEdit()
    
    editorAccount.setName("announcement.editor")
    editorAccount.setEmail("as@as.net")
    visitorAccount.setName("announcement.visitor")
    visitorAccount.setEmail("vs@vs.net")

    long accountEditorId = accEng.create(editorAccount, "editor") //(12)
    long accountVisitorId = accEng.create(visitorAccount, "visitor")

    // Add users to user groups
    accEng.addGroup(accountEditorId, uGroupEditors) //(13)
    accEng.addGroup(accountVisitorId, uGroupVisitors)

    // Assign type ACL to user groups
    aclEng.assign(announcementTypeACLId, uGroupEditors, ACL.Permission.READ, ACL.Permission.EDIT, ACL.Permission.CREATE, ACL.Permission.DELETE) //(14)
    aclEng.assign(announcementTypeACLId, uGroupVisitors, ACL.Permission.READ) //(15)

    // Create an instance ACL where both user groups have instance read permission
    // and editors also have edit and delete permission
    long instanceAclReadAllId = aclEng.create( //(16)
            "Announcement Instance Read All",
            new FxString("Announcement Instance Read All"),
            FxContext.get().getTicket().getMandatorId(),
            "#CC9900",
            "Announcement Instance Read All",
            ACL.Category.INSTANCE
    )
    // Assign "read all"-instance ACL to user group
    aclEng.assign(instanceAclReadAllId, uGroupEditors, ACL.Permission.READ, ACL.Permission.EDIT, ACL.Permission.CREATE, ACL.Permission.DELETE)
    aclEng.assign(instanceAclReadAllId, uGroupVisitors, ACL.Permission.READ)

    // Create instance ACL where only editors have instance read permission
    long instanceAclEditorsOnlyId = aclEng.create( //(17)
            "Announcement Instance Editors Only",
            new FxString("Announcement Instance Editors Only"),
            FxContext.get().getTicket().getMandatorId(),
            "#CC9900",
            "Announcement Instance Editors Only",
            ACL.Category.INSTANCE
    )
    // assign "editors only"-instance ACL to user group
    aclEng.assign(instanceAclEditorsOnlyId, uGroupEditors, ACL.Permission.READ, ACL.Permission.EDIT, ACL.Permission.CREATE, ACL.Permission.DELETE) //(18)
}

Datastructure setup

(1) An Access Control List (ACL) of category ACL.Category.STRUCTURE is created.

(2) The method call announcementEntry(...) will create the [fleXive] FxType announcementEntry which represents the data structure of an announcement instance.

Type and instance permissions are enabled

(3) Enabling the type permissions means that we can assign an ACL of category ACL.Category.STRUCTURE to the FxType announcementEntry. Every instance of the FxType announcementEntry will then have the same type permissions ACL which is checked whenever a user tries to create, read, edit, delete, relate or export an instance of this type.
(4) To achieve finer grained access control we have also enabled instance permissions. So additionally to the type permission ACL which is the same for every instance we can assign an ACL of category ACL.Category.INSTANCE to an individual instance. That means that all instances have the same type permission ACL, but the instance permission ACL may vary among instances.
(5) The previously defined structure ACL is assigned as type permissions ACL.

The fields of announcementEntry

In [fleXive] the field of an FxType is called property and cannot exist without being assigned to a FxType, but can be reused among different FxTypes. For an announcementEntry the following fields are defined:

(6) The system-internal caption property is reused to save the title of an announcement, as this property has some special features regarding the [flexive] backend:
The text that the caption property holds is what we see when displaying content instances in the content tree and when searching in the backend. Therefore using the caption property to hold the title of an announcement comes in naturally and helps us to distinguish between different announcements.
(7, 8) publishDate and publishURL have a multiplicity of 0..1, allowing them to be optional since the date of submission the publish date and url of the announcement are not known at the time of entry.
(9) For announcementText the option "multiline" is enabled. This means that when rendering this property a multi-line text input area will be used, instead of a normal single-line input field.

Setting up user groups and user accounts

(10) Two user groups, editors and visitors are defined.
(11) Then two user account objects are created and login names are set and the required e-mail address.
(12) Next the account objects are used to create a new account via the account engine's create(account, password) method where the passwords are set.
(13) Finally the editor account is added to the editors user group and the visitor account to the visitors user group.

Settings permissions for user groups

In [flexive] permissions for an instance are set on user group level.
(14, 15) We assign the ACL that we have used as type permission ACL for announcementEntry to the editors user group with create, update, read and edit (CRUD) permission. The visitors user group is only granted read permission.
(16) An instance ACL is created and assigned to the editors with CRUD permissions, whereas the visitors are only granted read permission.
(17, 18) Another instance ACL named "Announcement Instance Editors Only" is created that is assigned to the editors user group only. That means that if an announcementEntry instance has this ACL assigned, a user of the user group visitors has no permissions whatsoever on this instance.