Setting and Retrieving Runtime Permissions

While other permissions are bound to model elements in the process model, runtime permissions can be set via API.

Global level declarative security permissions can be set and retrieved at runtime.

RuntimePermissions

The RuntimePermissions interface serves as object which contains functionality to assign ModelPartitipant IDs, like Roles or Organizations, as granted for a specific permissionId.

/**
 * RuntimePermissions present permissions that are changeable at runtime. While other
 * permissions are bound to model elements in the process model RuntimePermissions can be
 * set via the public API.
 *
 */
public interface RuntimePermissions extends Serializable
{

   /**
    * Retrieves a set of all permissionIds which can be used to set and retrieve grants
    * for.
    *
    * @return all permissionIds
    * @see GlobalPermissionConstants
    */
   public Set<String> getAllPermissionIds();

   /**
    * Retrieves the currently set grants for the Permission.
    * If the all-grant is set this list is empty.
    *
    * @param permissionId
    * @return
    * @see GlobalPermissionConstants
    * @see RuntimePermissions#hasAllGrant(String)
    */
   public Set<ModelParticipantInfo> getGrants(String permissionId);

   /**
    * Allows setting a set of <code>ModelParticipant</code>. This can be used to
    * grant the specified Permission for certain Roles or Organizations.
    *
    * @param permissionId
    * @param grants a set of grants which will replace the existing ones.
    * @see GlobalPermissionConstants
    */
   public void setGrants(String permissionId, Set<ModelParticipantInfo> grants);

   /**
    * Sets the all-grant to the specified Permission.
    * By doing this all other grants will be removed.
    *
    * @param permissionId
    * @see GlobalPermissionConstants
    */
   public void setAllGrant(String permissionId);

   /**
    * Allows to check if the all-grant is set for the
    * specified permissionId.
    *
    * @param permissionId
    * @return
    * @see GlobalPermissionConstants
    */
   public boolean hasAllGrant(String permissionId);

   /**
    * Allows to check if the currently set grants are the default grants for the specified.
    * permissionId
    *
    * @param permissionId
    * @return
    * @see GlobalPermissionConstants
    */
   public boolean isDefaultGrant(String permissionId);

}

If the permission should be granted to every user, the grant RuntimePermissions.ALL_GRANT or, for convenience, RuntimePermissions.setAllGrant(String permissionId) can be used. Available permissionIds can be retrieved by RuntimePermissions.getAllPermissionIds().

Please refer to the JavaDoc of org.eclipse.stardust.engine.api.runtime.RuntimePermissions for details on the interface.

Available PermissionIds

The following permissionIds are provided:

• controlProcessEngine - permission to flush the cache.
• createCase - permission to create process instance case.
• deployProcessModel - permission to deploy a process model to the engine.
• manageDaemons - permission to start, stop and query the state of the daemons.
• modifyAuditTrail - permission to modify the AuditTrail database.
• modifyUserData - permission to modify user data such as email, account, etc.
• readAuditTrailStatistics - permission to query statistics on the audit trail database.
• readModelData - permission to access data contained in the model.
• readUserData - permission to access user data such as email, account, etc.
• modifyDepartments - permission to modify departments.
• readDepartments - permission to read department information.
• resetUserPassword - permission to reset the password of an user.
• manageAuthorization - permission to change user grants.
• runRecovery - permission to run the recovery.
• forceSuspend - permission to suspend an activity of another user.
• saveOwnUserScopePreferences - permission to save preferences in own user scope.
• saveOwnRealmScopePreferences - permission to save preferences in own realm scope.
• saveOwnPartitionScopePreferences - permission to save preferences in own partition scope.
• joinProcessInstance - permission to join a process instance.
• spawnPeerProcessInstance - permission to spawn a peer process instance.
• spawnSubProcessInstance - permission to spawn a sub process instance. The API to retrieve list of startable processes to spawn should be guarded by the permission Obtain Data Model.

Please refer to chapter Declarative Security Usage in Stardust Services API for details on these permissions.

Retrieving and Setting Global Runtime Permissions

In the Stardust services, methods to retrieve and set global permissions are used as described in the following sections.

Retrieving Global Permissions

To retrieve permissions, that are globally set, use a method that returns a RuntimePermissions object, which is described in section RuntimePermissions. Such permissions could be permissions concerning model deployment, preference saving, modifying AuditTrail or managing daemons.

public RuntimePermissions getGlobalPermissions();

For details on this method, refer to the Javadoc of the AdministrationService.

Setting Global Permissions

To set global permissions, use the method setGlobalPermissions(RuntimePermissions permissions).

public void setGlobalPermissions(RuntimePermissions permissions) throws AccessForbiddenException;

This method saves the modified permissions set in the permissions parameter, which is an object of RuntimePermissions. Permissions with value null or empty lists set as grants will be reset to their internal default.

In case the current user does not have the required privilege, an AccessForbiddenException is thrown. A NullPointerException occurs, if permissions is null.

Grants are set by providing a ModelParticipantInfo object using the setGrants method. The following special ModelParticipantInfo exists for granting the Administrator role: org.eclipse.stardust.engine.api.model.ModelParticipantInfo.ADMINISTRATOR.

To perform the setGlobalPermissions method, the saveOwnPartitionScopePreferences grant is required.

For details on this method, refer to the Javadoc of the AdministrationService.

Verification of changed grants

Changed grants are verified against active models. Trying to add a grant using a ModelParticipantInfo, that does not exist in the active model, leads to a validation exception.

Granting permission to all users

If the permission should be granted to every user, the convenience method RuntimePermissions.setAllGrant(String permissionId) should be used. This removes all other grants which are set.