Imixs Workflow ...the open source workflow technology for business applications

Engine

JEE Security Configuration (ACL)

Each method call to the Imixs Workflow System have to possess an applicable authentication process to grant the demands of the Imixs Workflow technology according security.

An implementation should not allow anonymous access. Each user should be mapped to one of the Imixs Access Roles.

Rolemapping in the Deployment Descriptor

In the security concept of the workflow there are 5 roles defined:

  • org.imixs.ACCESSLEVEL.NOACCESS
  • org.imixs.ACCESSLEVEL.READACCESS
  • org.imixs.ACCESSLEVEL.AUTHORACCESS
  • org.imixs.ACCESSLEVEL.EDITORACCESS
  • org.imixs.ACCESSLEVEL.MANAGERACCESS

So you have to map these roles in your application to corresponding groups form defined authentication realm.

See following example shows a sun-web.xml deployment descriptor for Glassfish Server which maps these roles to corresponding groups:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sun-web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Application Server 9.0 Servlet 2.5//EN" "http://www.sun.com/software/appserver/dtds/sun-web-app_2_5-0.dtd">
<sun-web-app error-url="">
  <context-root>/org.imixs.openissue.web</context-root>
      <security-role-mapping>         
        <role-name>org.imixs.ACCESSLEVEL.NOACCESS</role-name>         
        <group-name>Imixs_IX_Demo_Noaccess</group-name>    
    </security-role-mapping>

    <security-role-mapping>         
        <role-name>org.imixs.ACCESSLEVEL.READERACCESS</role-name>         
        <group-name>Imixs_IX_Demo_Reader</group-name>    
    </security-role-mapping>

    <security-role-mapping>         
        <role-name>org.imixs.ACCESSLEVEL.AUTHORACCESS</role-name>         
        <group-name>Imixs_IX_Demo_Author</group-name>    
    </security-role-mapping>

    <security-role-mapping>         
        <role-name>org.imixs.ACCESSLEVEL.EDITORACCESS</role-name>         
        <group-name>Imixs_IX_Demo_Editor</group-name>    
    </security-role-mapping>

    <security-role-mapping>         
        <role-name>org.imixs.ACCESSLEVEL.MANAGERACCESS</role-name>         
        <group-name>Imixs_IX_Demo_Manager</group-name>    
    </security-role-mapping>
</sun-web-app>

This mapping should also be done in the sun-ejb-jar.xml inside an EJB module

sun-application.xml

If you combine web and ejb modules in a ear module you can use the sun-application.xml to overwrite all of these deployment descriptors. This is more easy to use.

See the following example which shows an sun-application.xml which overrides roles mappings and also the ream defined in web.xml files:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sun-application PUBLIC "-//Sun Microsystems, Inc.//DTD Application Server 9.0 Java EE Application 5.0//EN" "http://www.sun.com/software/appserver/dtds/sun-application_5_0-0.dtd">
<sun-application>

    <security-role-mapping>
        <role-name>org.imixs.ACCESSLEVEL.NOACCESS</role-name>
        <group-name>Imixs_IX_Demo_Noaccess</group-name>
    </security-role-mapping>

    <security-role-mapping>
        <role-name>org.imixs.ACCESSLEVEL.READERACCESS</role-name>
        <group-name>Imixs_IX_Demo_Reader</group-name>
    </security-role-mapping>

    <security-role-mapping>
        <role-name>org.imixs.ACCESSLEVEL.AUTHORACCESS</role-name>
        <group-name>Imixs_IX_Demo_Author</group-name>
    </security-role-mapping>

    <security-role-mapping>
        <role-name>org.imixs.ACCESSLEVEL.EDITORACCESS</role-name>
        <group-name>Imixs_IX_Demo_Editor</group-name>
    </security-role-mapping>

    <security-role-mapping>
        <role-name>org.imixs.ACCESSLEVEL.MANAGERACCESS</role-name>
        <group-name>Imixs_IX_Demo_Manager</group-name>
    </security-role-mapping>

    <realm>imixsrealm</realm>

</sun-application>

security-role-ref

To map these roles in a web application directly without the deployment descriptors above use the security-role-ref in the web.xml and ejb-jar.xml as defined in the JEE specification.

  ...  
   <security-role-ref>
    <role-name>author</role-name>
    <role-link>org.imixs.ACCESSLEVEL.AUTHORACCESS</role-link>
  </security-role-ref>
...

In this example name in the role-link must match the name of the imixs security role and the role-name to a group or role in your security context.

Note:
It is recommended to use the sun-application.xml descriptor.

Defining application specific access roles

In addition to the standard security model of the Imixs Workflow System you can also specify application specific roles. These roles can be used in a Workflow application to restrict the access in a more fine grained way. An application specific role is typical mapped to a workitem by using the Imixs Workflow Modeler. You can add such a Role to the Read or Write Access configuration of an Activity Entity. The Workflow Manager will map the application specific role later directly into a workitem.

Note:
Users must have at least the general AccessRole org.imixs.ACCESSLEVEL.READACCESS to access a workitem. Also if you define application specific roles. Otherwise a uses is not allowed to access the workitems with an application specific role restriction in the WorkfloManager.

Example

For example you may add an additional application specific role named "PROJECTMANAGER" to your workflow application. You can restrict the access (read and write access) to that new role for all workitems in a specific workflow status by defining this role in your model.

To use such an application specific role like "PROJECTMANAGER" you need to define this role in the ejb deployment descriptor (ejb-jar.xml) and map this role also to a UserGroup (sun-ejb-jar.xml) as described above.

The following code example illustrates how to define an application specific role in the deployment descriptor:

ejb-jar.xml
  <enterprise-beans>
 .....
 <session>
        <ejb-name>EntityServiceBean</ejb-name>
        <ejb-class>org.imixs.workflow.jee.ejb.EntityServiceBean</ejb-class>
        <session-type>Stateless</session-type>
        <env-entry>
                <description>Additional Access Rolls</description>
                <env-entry-name>ACCESS_ROLES</env-entry-name>
                <env-entry-type>java.lang.String</env-entry-type>
                <env-entry-value>com.prosamed.ISESS.ARTIKELMODIFIER</env-entry-value>
        </env-entry>
        <security-role-ref>
                <role-name>PROJECTMANAGER</role-name>
                <role-link>PROJECTMANAGER</role-link>
        </security-role-ref>
 </session>
 ...
 .....
  <assembly-descriptor>
                <security-role>
                        <role-name>PROJECTMANAGER</role-name>
                </security-role>
  </assembly-descriptor>

To link the new Role to the Imixs Workflow components it is adequate to define the role to the EntiyServiceBean. There you need to add two additional entries.

The env-entry defines the new role to be used by the access control of the EntityServiceBean. The security-role-ref adds the role to the EJB. You need to specifiy the role-name and also the role-link for an additional role.

If you need to access those role definitions also from other EJBs like the WorkflowService ore from a WorkflowPlugins, you need to add the additional security-role-ref tags also to the corresponding ejb definitions.

At the end of the eja-jar.xml is is also necessary to add an assemble-descriptor. In this section you define the new role which will be linked to the role mapping used in the sun-application.xml (or sun-ejb-jar.xml).

sun-ejb-jar.xml
...
    <security-role-mapping>
        <role-name>PROJECTMANAGER</role-name>
        <group-name>ProjectManagers</group-name>
    </security-role-mapping>
...