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 ModelParticipant IDs, like Roles or Organizations, as granted or denied for a specific permissionId.

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

Available Runtime PermissionIds

The following permissionIds are provided:

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

Retrieving all available Permission Ids

Method getAllPermissionIds retrieves all permissionIds, which can be used to set and retrieve grants:

   /**
    * Retrieves a set of all permissionIds which 
    * for.
    *
    * @return all permissionIds
    * @see GlobalPermissionConstants
    */
   public Set<String> getAllPermissionIds();

Retrieving the Grants set for a Permission

Method getGrants(String permissionId) returns the currently set grants for the specified permission:

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

Retrieving the Denied Grants set for a Permission

Method getDeniedGrants retrieves the currently set denied grants for a specified permission:

   /**
    * Retrieves the currently set of denied grants for the Permission.
    * If the all-grant is set this set is empty.
    *
    * @param permissionId the id of the permission from <code>GlobalPermissionConstants</code>
    * @return the currently denied grants.
    * @see GlobalPermissionConstants
    * @see RuntimePermissions#hasAllGrant(String)
    */
   public Set<ModelParticipantInfo> getDeniedGrants(String permissionId);

Granting a specified Permission to a set of Participants

Method setGrants allows to set a set of model participants to be used to grant a specified permission for certain roles or organizations:

   /**
    * Allows setting a set of <code>ModelParticipantInfo</code>. This can be used to
    * grant the specified Permission for certain Roles or Organizations.
    * The <code>ModelParticipantInfo</code> must not be scoped with a department.
    *
    * @param permissionId the id of the permission from <code>GlobalPermissionConstants</code>
    * @param grants a set of grants which will replace the existing ones.
    * @see GlobalPermissionConstants
    * @throws IllegalArgumentException If the <code>ModelParticipantInfo</code> is department scoped.
    */
   public void setGrants(String permissionId, Set<ModelParticipantInfo> grants);

Denying the Grant for a specified Permission to a set of Participants

Method setDeniedGrants allows to set a set of model participants to be used to deny grants for a specified permission for certain roles or organizations:

   /**
    * Allows setting a set of <code>ModelParticipantInfo</code> corresponding to a denied
    * grant to the specified Permission for certain Roles or Organizations.
    * The <code>ModelParticipantInfo</code> must not be scoped with a department.
    *
    * @param permissionId the id of the permission from <code>GlobalPermissionConstants</code>
    * @param grants a set of denied grants which will replace the existing ones.
    * @see GlobalPermissionConstants
    * @throws IllegalArgumentException If the <code>ModelParticipantInfo</code> is department scoped.
    */
   public void setDeniedGrants(String permissionId, Set<ModelParticipantInfo> grants);

Setting all Grants for a specified Permission

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

Note that all other grants and denied grants will be removed when this method is used.

   /**
    * Sets the all-grant to the specified Permission.
    * By doing this all other grants and denied grants will be removed.
    *
    * @param permissionId the id of the permission from <code>GlobalPermissionConstants</code>
    * @see GlobalPermissionConstants
    */
   public void setAllGrant(String permissionId);

Checking if a Permission has all Grants

Method hasAllGrant checks if the ALL grant is set for a specified permissionId:

   /**
    * Allows to check if the all-grant is set for the
    * specified permissionId.
    *
    * @param permissionId the id of the permission from <code>GlobalPermissionConstants</code>
    * @return <code>true</code> if the all-grant is set for the specified permissionId.
    * @see GlobalPermissionConstants
    */
   public boolean hasAllGrant(String permissionId);

Checking if the set Grants are the Default Grants for a specified Permission

Method isDefaultGrant checks if the currently set grants are the default grants for a specified permissionId.

public interface RuntimePermissions extends Serializable
{
   /**
    * Allows to check if the currently set grants are the default grants for the specified.
    * permissionId
    *
    * @param permissionId the id of the permission from <code>GlobalPermissionConstants</code>
    * @return <code>true</code> if the specified permissionId currently has its default grant assigned.
    * @see GlobalPermissionConstants
    */
   public boolean isDefaultGrant(String permissionId);

}

Retrieving and Setting Global Runtime Permissions

In the Infinity Process Platform 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. Please refer to section Setting all Grants for a specified Permission for details.