Setting Up Permissions and Roles

Prior to version 2021.3.0, data security was configured within the technical administration and required programming skills to define security rules.

Starting from version 2021.3.0, application provides a mechanism for securing data access without requiring access to the technical admin interface, nore specific programming knowledge.

Requirements

• Plugin PACKAGED_Security installed and activated

• Structures pkgsecugroup and pkgsecupermission restored on application

• Make use of plugin provided macros in security rules

• Eligible structures must be identified

Overview

Permissions pkgsecupermission

A permission represents an authorized action.

Permission are defined by giving a functional name (property name) and a permission key (property permission).

A permission grants a right for a context. The given right is resolved by analyzing the permission property. Permission follows the following pattern:

<version>/<domain>/<action>/[modifiers]+

For instance named “Update owned offline“ with permission v1/objectdata/update/$offline/$selfownermeans that a user having this permission on an object is allowed to update instances in an offline status (status is not online and not archived) that he owns object.owner == surfer.id

Patterns

• version: The only available version for patterns is v1 but introducing a version in patterns will ease further improvements and ease ascendent compatibility. Until new versions are available, just keep in mind that natively handled permissions start with “v1”.

• domain: The domain of the security rule that this permission will act on. As of 2021.3.0, objectdataand boards are handled

• action: The action within the domain that this permission will act on. As of 2021.3.0, all actions from objectdata domain can be handled.

• modifiers: Modifiers will define the context for which the action will be granted. Modifiers vary from one action to the other:

  • objectdata

    • insert action: 1 modifier is to be defined: creationMode. Therefore, all insert permissions follow this pattern: v1/objectdata/insert/<creationMode>

    • changestatus action: 3 modifiers are to be defined: workflowAction, instanceStatus, ownership. Therefore, all changestatus permissions follow this pattern: v1/objectdata/changestatus/<workflowAction>/<instanceStatus>/<ownership>

    • other objectdata actions (delete, i18nfieldstranslate, order, retrievecaption, update, view): 2 modifiers are to be defined: instanceStatus, ownership. Therefore, all those actions follow this pattern: v1/objectdata/<action>/<instanceStatus>/<ownership>

  • boards

    • makepublicboard action: No modifiers - permission is granted or not

    • shareboard action: 3 modifiers are to be defined: boardVisibility, boardType, ownership,

Modifiers

Each modifier supports specific keywords to finely define the context.

boardVisibility

Allows to limit permission based on boards visibility:

• $publicboard: Grants permission on a public board (private = 2)

• $privateboard: Grants permission on a private board (private = 1)

• $anyvisibilityboard: Grants permission regardless of visibility

boardType

Allows to limit permission based on the type of board:

• $anyboardtype: Grants permission on any type of board

• <type>: Grants permission on board of type <type>

creationMode

Creation mode represents how the instance is created. 3 keywords are available:

• $newcreation: Creating a fresh instance (eg click on the “New” button)

• $copycreation: Create an instance by duplicating an existing one or by creating a workcopy

• $anycreation: Any creation mode

workflowAction

Workflow action represents the action that is performed on the object from a workflow perspective. 6 keywords are available:

• $publish: Publishing action: performing a workflow action that will move the instance in an online marked state

• $archive: Archiving action: performing a workflow action that will move the instance in an archived marked state

• $forward: Forward action: performing an action marked forward, and that will not lead to online or archived marked state.

• $backward: Backward action: performing an action NOT marked forward, and that will not lead to online or archived marked state.

• $process: Any process action: performing that will not lead to online or archived marked state.

• $anyaction: Any workflow action (including publishing and archiving actions)

• <actionName>: If none of the above keywords, the action name is taken as is and resolved base on the instance’s workflow

instanceStatus

Instance status represents the current status of the object from a workflow perspective. 5 keywords are available:

• $online: An online marked state

• $archived: An archived marked state

• $offline: A state that is neither marked online not archived

• $initialstatus: The initial state of the instance (usually = 2)

• $anystatus: Any state

• <customMetaStatus>: It is possible to create custom names regrouping several states (see further)

ownership

Ownership allows to limit a permission to the owner property of an instance. 2 keywords are available

• $selfowner: User must be the owner of the instance to be able to perform an action

• $anyowner: No restriction on ownership

• $boardcollaborator: Specific to boards domain - Identify the surfer as a collaborator on a board

Groups pkgsecugroup

Groups allow to centralize multiple permissions on one or many obects, for one or many roles and one or many users.

• name: Name of the group

• template (boolean): it is convenient to have groups as templates. If template is true, then this instance is not used when resolving groups to which belong a user

• activated (boolean): Inactive instances are ignored

• objectsselector (string): A structure selector to define which objects are managed by the group. For instance:

  • assetkeyword would apply to structure named assetkeyword.

  • #damobject would apply to any structure having the tag damobject (on table level)

  • assetkeyword,#damobject would apply to structure assetkeyword and to any object having the tag damobject

• permissions (childmulti → pkgsecupermission): Permissions granted to users belonging to this group for objects matching objectselector

• roles (childmulti →role): All users of selected roles will be members of the group

• users (childmulti →user): All users selected will be members of this group

Identifying eligible structures

Structures eligibles to permission granting are marked with one or multiple table tags :

pkg/security/secugroup/<action> or pkg/security/secugroup/all

this means that to be able to manage view permissions on object foo, foo table configuration must have either pkg/security/secugroup/view or pkg/security/secugroup/all

Installing the feature

Initializing data

The default NAR file contains the required structures for managing the rights, but to ease migrations, and upgrades, the NAR file does not contains neither permissions definitions nor groups:

Providing default values would force some ids with functional meanings on permissions, groups, roles and eventually users, which is obviously not desired as each projects needs defines different roles, each project will make use of some permissions, but not all the possible ones…

Additionally, delivering configured permissions or groups directly in the NAR file would increase migration complexity as product added permissions and product added groups might come in conflict with projects definitions.

As the whole system only relies on permission strings, a service API is provided to “fill the gap” between actual values in DB and what the product team recommends to create:

/api/packaged/admin/security/update

This API requires Administrators or TestOperators HTTP role to be executed as well as the right to create instances of pkgsecupermission and pkgsecugroup

This API will check current data in pkgsecupermission and pkgsecugroup and create missing data in both structures. Additional information is provided in the swagger UI.

• permissions are identified based on the permission string

• groups are identified based on their name.

Product team will only provide templates for groups. Product team will always give template names with brackets.

It is recommended to identify project specific template with either a prefix or a suffix

Make usage of the permissions

Permissions handled by the plugin are just a tool allowing to give you more flexibility to your rules, but they can be combined with any project specific rules.

The plugin provides a security macro per domain with the camel-cased name pkg<version><domain>. These macro will be installed first time you activate the plugin.

You will need to make usage of these macros in your security rules:

For instance on objectdata/update, you can define a single rule “Packaged updates“ with following code:

@pkgV1Objectdata('update')

Of course you might have more specific rules regarding users' rights on specific objects, but you can always use the macros as a starting point:

For instance, this call is perfectly fine

STRUCTUREHASTAG(objectname, 'damobject')
AND
NBCOMMONELEMENTS(object.someproperty, surfer.someproperty) > 0
AND 
@pkgV1Objectdata('update')

You could even add additional rules like to be able to update an object, you should be allowed to view it. In such a case, the rule could be written as

In objectdata/update, rule “To update, must also be allowed to view”

@pkgV1Objectdata('view') AND @pkgV1Objectdata('update')

Extending capabilities

Meta statuses definitions

Quite often, you will need to identify workflow statuses as specific, but will not be able to rely on native keywords. For instance, you might want to identify what are the “validation steps” to be able to create permissions that will only apply to those statuses.

You can achieve this by configuring the plugin parameter meta_statuses:

This parameter is JSON. It accepts either null or a JsonObject.

If null, then no specific “metastatuses” are defined.

If a JsonObject, each key is a metaStatus name (exemple: “validationStep”). Associated value can be either

• an array of ids that corresponds to ids matching the metastatus

• an object for which each key is the name of a workflow or default ; metastatuses will then be resolved based on the workflow name or default if not found

Custom permission resolver

It is possible to configure a specific groovy script to resolve permissions in the surfer:

In plugin, configure custom_permissions_builder to the SAN based groovy script path to your desired implementation. (When saving, the groovy script will be created if not exists, with sample code)

Troubleshooting

Datamodel compliance

You can check the compliance of your data model by accessing

/api/packaged/admin/security/validators/model/html

• if first line is green, the data model is good

• if first line is yellow, you could improve it

• if first line is red, it won’t work

Testing a user

You can check what the plugin has resolved for a user by calling

/api/packaged/admin/security/surfer-keys/<userId>

Cheat sheet

Find for each managed domain / action, the permission pattern

Find available values for modifiers