Transact

⌘K
  1. Home
  2. Transact
  3. System Configuration
  4. User Connectivity
  5. How to Administer Ephesoft Users and Groups

How to Administer Ephesoft Users and Groups

Ephesoft supports Tomcat, OpenLDAP and Microsoft Active Directory protocols for maintain a roster of users and groups. OpenLDAP is the default management system that is enabled and configured following a clean installation of Ephesoft Transact. There are two main configuration files:

  • {EPHESOFT_ROOT_DIR}\Application\WEB-INF\classes\META-INF\dcma-user-connectivity\user-connectivity.properties

This file contains the settings necassary to populate groups names in Ephesoft Batch Class Management. The file contains settings for LDAP, Tomcat and MS Active Directory.

  • {EPHESOFT_ROOT_DIR}\JavaAppServer\conf\server.xml
    • NOTE: IN EPHESOFT v2.5 Realm settings are located in {EPHESOFT_ROOT_DIR}\JavaAppServer\conf\Catalina\localhost\dcma.xml INSTEAD OF server.xml

This file tells Ephesoft how users should be authenticated when they are login into the Ephesoft. The file should have following Realm:

Configuring Apache-Tomcat

Apache-Tomcat configuration is enabled in three different files:

  • {EPHESOFT_ROOT_DIR}\Application\WEB-INF\classes\META-INF\dcma-user-connectivity\user-connectivity.properties

This file contains the settings necassary to populate groups names in Ephesoft Batch Class Management. The following settings should be set for Tomcat:

user.tomcatUserXmlPath={EPHESOFT_ROOT_DIR}\\JavaAppServer\\conf\\tomcat-users.xml
user.connection=2
  • {EPHESOFT_ROOT_DIR}\JavaAppServer\conf\server.xml
    • NOTE: IN EPHESOFT v2.5 Realm settings are located in {EPHESOFT_ROOT_DIR}\JavaAppServer\conf\Catalina\localhost\dcma.xml INSTEAD OF server.xml

This file tells Ephesoft that users should be authenticated using tomcat. The file should have following Realm:

<Realm className="org.apache.catalina.realm.MemoryRealm"/> 
  • {EPHESOFT_ROOT_DIR}\JavaAppServer\conf\tomcat-users.xml

This file contains user groups and users. For example a group called admin and a user called ephesoft with password demo is defined as follows:

  <role rolename="admin"/>
  <user username="ephesoft" password="demo" roles="admin"/>

Configuring OpenLDAP

OpenLDAP Software is a free, open source implementation of the Lightweight Directory Access Protocol (LDAP) developed by the OpenLDAP Project. It is released under its own BSD-style license called the OpenLDAP Public License. LDAP is a platform-independent protocol. To connect to the Ephesoft LDAP database and modify groups, users, permissions, etc administrators can utilize the bundled JExplorer tool @ the following location:

  • {EPHESOFT_ROOT_DIR}\Dependencies\OpenLDAP\ldap-client\jxplorer-3.2.1\jxplorer.bat

Connection to LDAP configuration is enabled in two different files:

  • {EPHESOFT_ROOT_DIR}\Application\WEB-INF\classes\META-INF\dcma-user-connectivity\user-connectivity.properties

This file contains the settings necassary to populate groups names in Ephesoft Batch Class Management. The following settings should be set for LDAP configuration:

user.ldap_url=ldap://localhost:389
user.ldap_config=com.sun.jndi.ldap.LdapCtxFactory
user.ldap_domain_component_name=ephesoft
user.ldap_domain_component_organization=com
user.ldap_username=cn=Manager,dc=ephesoft,dc=com
user.ldap_password=*******
user.connection=0
  • {EPHESOFT_ROOT_DIR}\JavaAppServer\conf\server.xml
    • NOTE: IN EPHESOFT v2.5 Realm settings are located in {EPHESOFT_ROOT_DIR}\JavaAppServer\conf\Catalina\localhost\dcma.xml INSTEAD OF server.xml

This file tells Ephesoft that users should be authenticated using tomcat. The file should have following Realm:

<Realm   className="org.apache.catalina.realm.JNDIRealm"
connectionURL="ldap://localhost:389"
connectionName="cn=Manager,dc=ephesoft,dc=com"
connectionPassword="secret"
userPattern="cn={0},ou=people,dc=ephesoft,dc=com"
roleBase="ou=groups,dc=ephesoft,dc=com"
roleName="cn"
roleSearch="uniqueMember={0}"
/>

Configuring Active Directory

Update – Configuring Active Directory Globally (Applies to v3.0 or Higher)

Requirement: Latest dcma-user-connectivity-0.0.15.jar [5]

Objective:

  • Using root domain(Domain components DC only) as user base and role base for authentication using LDAP/MS Active directory.
  • Possibly having a single and convenient realm to handle all requests.

Proposed Solution:

  • Enhancing LDAP and MS Active directory to be able to provide authentication having the knowledge of root domain only.
  • Setting up the realm for providing the same.
  • Updating jars to handle this scenario.

Solution:

  • MS Active directory
  • MS Active Directory works on various ports for different purposes.
  • Port 389 is for normal LDAP working of MS Active Directory.
  • Port 3268 is for Global catalog working of MS Active Directory.
  • MS Active directory working as simple LDAP service cannot handle root domain search requests. This is Because Searching a root domain in Active directory returns referrals to the root components which can only be handled by Global catalog service and not by normal LDAP service.

To do this you will modify the user-connectivity.properties file located in:

Epehesoft Install Directory\Application\WEB-INF\classes\META-INF\dcma-user-connectivity

  • Set the “user.msactivedirectory_url” to “ldap://<Server-Name/IP>:3268
  • Set the “user.msactivedirectory_context_path” to empty
  • Set the “user.msactivedirectory_group_search_filter” to a single filter value. (Not multiple filters to be specified)

This setting will be in sync with the one done while setting the Realm.

Setting changes to LDAP

Normal LDAP service allows us to search on root domain without any further configuration. So there is not much change to be made in order to make LDAP work with root domain chosen as base. Following are the changes:

  • Set the “user.ldap_user_base” to empty.
  • Set the “user.ldap_group_base” to empty.

**Note**: these properties are added in the Installer version 3.0.2.0 onwards. Please update your properties file with the Changes mentioned if running versions prior to 3.0.2.0.

Sample Configuration for User-connectivity.properties file:

    user.ldap_url=ldap://localhost:389
    user.ldap_config=com.sun.jndi.ldap.LdapCtxFactory
    user.ldap_domain_component_name=ephesoft
    user.ldap_domain_component_organization=com
    user.ldap_username=cn=Manager,dc=ephesoft,dc=com
    user.ldap_password=secret
    user.ldap_user_base=
    user.ldap_group_base=
            user.msactivedirectory_url=ldap://msad.ephesoft.com:3268
            user.msactivedirectory_config=com.sun.jndi.ldap.LdapCtxFactory
            user.msactivedirectory_context_path=
            user.msactivedirectory_domain_component_name=ephesoft
            user.msactivedirectory_domain_component_organization=com
            user.msactivedirectory_user_name=CN=administrator,DC=ephesoft,DC=com
            user.msactivedirectory_password=Passw0rd
                  # filter can have |(OR), &(AND) and !(NOT)
                  # | (|(cn=a*))
                  # & (&(cn=a*))
                  # ! (!(cn=a*))
                  # complex example ((!(cn=a*))(|(cn=ephesoft*)(&(cn=b*)))
                  user.msactivedirectory_group_search_filter=(!(cn=*h*oft*))
                  user.tomcatUserXmlPath=C:\\Ephesoft\\JavaAppServer/conf/tomcat-users.xml
    # 0 for LDAP
    # 1 for MS Active Directory
    # 2 for Tomcat
    user.connection=1

Next you will need to modify the Realm settings in the Server.XML file located in:

Epehesoft Install Directory\JavaAppServer\conf

    <Realm   className="org.apache.catalina.realm.JNDIRealm"
               connectionURL="ldap://<Server-Name/IP>:3268"
               connectionName="<Authenticated-User-Name>"
               connectionPassword="<Authenticated-User-Password>"
                     userBase="<Any Chosen User Base>"
                     userSearch="<Unique Parameter for user search Suggested: (sAMAccountName={0})>"
                     userSubtree="true"
                     referrals="follow"
                          roleBase="<Any Chosen User Base>"
                          roleName="cn"
                          roleSubtree="true"
                          roleSearch="(member={0})"
                                 
    />

Example Realm Configuration:

    <Realm   className="org.apache.catalina.realm.JNDIRealm"
               connectionURL="ldap://msad.ephesoft.com:3268"
               connectionName="CN=administrator,DC=ephesoft,DC=com"
               connectionPassword="password"
                   userBase="DC=ephesoft,DC=com"
                   userSearch="(sAMAccountName={0})"
                   userSubtree="true"
                   referrals="follow"
                       roleBase="DC=ephesoft,DC=com"
                       roleName="cn"
                       roleSubtree="true"
                       roleSearch="(member={0})"
                                 
    />

Specifying the AD Group as Super_Admin

To edit this you will need to navigate to the Following location:

Scroll to the setting below and remove the entry “admin” and replace with the Assigned AD Security Group.

user.super_admin=<GroupName>

Sample Application.properties:

  #Super admin group update disabled.
    ephesoft.product.version=3.0.2.0
    report.ant.buildfile.path=C:\\Ephesoft\\Report/ephesoft-reporting/build.xml
    enable.reporting=true
    enable.uploadBatch=true
  #default doc type view can be "dropdown_list" or "suggest_box"
    document.default_doc_type_view=suggest_box_view
    function_key_script_name=ScriptFunctionKey
  #This property value has become obsolete. No need to set its value from version 3.0.2.0 onwards.
    tesseract_version_3=C:\\Ephesoft\\Application/native/Tesseract-OCR
    field_value_change_script_name=ScriptFieldValueChange
    row_count=50
    zip_switch=true
    update_interval=5
    preloaded_image_count=3
  #0 for html cleaner(default)
  #any other value for Tidy parser (Support for EE 2.4 or earlier)
    html_parser=0
    custom_reports_url=http://www.ephesoft.com
    custom_reports_title=Ephesoft
    custom_reports_pop_up_xdimension=500
    custom_reports_pop_up_ydimension=500
    enable.restart_all_batch=false
    batchlist.table_row_count=15
    zoom_count=1
    create_batch_instance_backup=off
    plugin_upload_folder_path=C:\\Ephesoft\\SharedFolders/plugin-upload-folder
    user.super_admin=admin
    help_url=http://www.ephesoft.com/wiki/index.php?title=Special:Search
    batch_copy_timeout=3600
  # 1-RoundRobin (Default)
  # 0-BatchInstancePriority
    workflow.batchPickingAlgo=1
  # false for review panel as closed on Review-Validation screen for batches with READY_FOR_VALIDATION state
  # true for review panel as open by default on Review-Validation screen for batches with READY_FOR_VALIDATION state
    default_review_panel_open=false
  # 0 for limited/metered user
  # 1 for shared user(not implemented)
  # 2 for dedicated
    user_type=2
  # file size limit in KB.
    upload_batch_limit=1024
  # Set this property as true if super admin roles has been updated
    update_super_admin_group=false

Update – Super Admin Group Setting in v3.0.2.0 or Higher

The following line has been added to the Application.properties file regarding applying changes to the user.super_admin Group.

  # Set this property as true if super admin roles has been updated
    update_super_admin_group=false

When changes are made to the user.super_admin line on the same file, you will need to set the above line to true. Then you will restart Ephesoft and it will set the new group as the Super Admin.

Limitations of this Solution

Issue: Choosing the below authentication may run into ambiguity. That is in case we have multiple users by same “name”(the user distinguishing parameter in realm). This will lead to a point where we cannot handle the client log in request as it will depend on LDAP/MS Active Directory implementations. It depends on how the concerned server will choose the user. Please see example:

Three users:

  • CN=admin, OU=sales, DC=ephesoft, DC=com
  • CN=admin, OU=java, OU=tech, DC=ephesoft, DC=com
  • CN=admin, OU=management, DC=ephesoft, DC=com
  • Realm “user base” set to domain components (DC=ephesoft, DC=com).
  • Realm “user search” set to “cn={0}”. (Checks for common name = <Value used for login>)
  • Intended user to log in CN=admin, OU=sales, DC=ephesoft, DC=com.

In the above scenario, the realm searches all child entries of DC=ephesoft, DC=com in LDAP/MS AD server with username(“admin”) to be equal to common name value of any user entry lying under “DC=ephesoft, DC=com”. In this case it will find the first matching entry and will authenticate against it. This chosen entry might not be the desired one. The point of concern here is choosing “user search” parameter carefully.

Solution:

  • Keep the “user search” value in realm in way that it can identify your user uniquely. That is the parameter used for searching a user must uniquely identify each of the user entries in LDAP/ MS AD.
  • Make the user enter the its value for that unique parameter into username while logging in to the application.
  • Keeping cn(common name), first name, last name as “user search” parameter may cause such scenario.

Configuring Active Directory at the OU Level

Written by – Pat Myers @ Zia consulting.

First you have to configure the Active Directory to pull the groups so you can set the role(s) for the batch classes. To do this you will modify the user-connectivity.properties file located in: Epehesoft Install Directory\Application\WEB-INF\classes\META-INF\dcma-user-connectivity

Set up the following properties for Active Directory:

user.msactivedirectory_url= ldap://YourDomain.com:389
user.msactivedirectory_config=com.sun.jndi.ldap.LdapCtxFactory
user.msactivedirectory_context_path=OU=Security Groups
user.msactivedirectory_domain_component_name=yourdomain
user.msactivedirectory_domain_component_organization=com
user.msactivedirectory_user_name=CN=Ephesoft Service,OU=Users,DC=YourDomain,DC=com
user.msactivedirectory_password=UserPassword
# filter can have |(OR), &(AND) and !(NOT)
# | (|(cn=a*))
# & (&(cn=a*))
# ! (!(cn=a*))
# complex example ((!(cn=a*))(|(cn=ephesoft*)(&(cn=b*)))
user.msactivedirectory_group_search_filter=
# 0 for LDAP
# 1 for MS Active Directory
# 2 for Tomcat
user.connection=1

user.msactivedirectory_url – This is the url to the LDAP server

user.msactivedirectory_context_path – path to root where groups reside. Multiple locations can be specified with a “;;” delimiter (eg. OU=Internal Groups;;OU=Contractors)

user.msactivedirectory_domain_component_name – component value for AD is DC below the root DC. There can only one value here such as ‘ephesoft’. ‘cn=na,cn=ephesoft’ or ‘cn=ephsesft’ is not allowed.

user.msactivedirectory_domain_component_organization – root DC of the AD store (typically “com”)

user.msactivedirectory_user_name – User name to connect to the AD server.

user.msactivedirectory_password – User password to connect to the AD server.

user.msactivedirectory_group_search_filter – Display only the groups that meets the filter value

user.connection – value should be set to 1 to read the AD configuration (opposed to LDAP or Tomcat properties)

If you have batch classes you should now restart the Ephesoft service set the roles for the batch classes.

Next you have to modify the path for authentication of the users. The file you have to modify is called server.xml and it is located in: {EPHESOFT_ROOT_DIR}\JavaAppServer\conf\ NOTE: IN EPHESOFT v2.5 Realm settings are located in {EPHESOFT_ROOT_DIR}\JavaAppServer\conf\Catalina\localhost\dcma.xml INSTEAD OF server.xml

Modify the realm element to have the url, name, password, pattern and role base for the Active Directory instance.

<Realm 
 className="org.apache.catalina.realm.JNDIRealm"
 connectionURL="ldap://YourDomain.com:389"
 connectionName="CN=Ephesoft Service,OU=Users,DC=YourDomain,DC=com"
 connectionPassword="UserPassword "
 userPattern="cn={0},OU=Users,DC=YourDomain,DC=com"
 roleBase="OU=Security Groups,DC=YourDomain,DC=com"
 roleSubtree=”true”
 roleName="cn"
 roleSearch="member={0}"
/>

Attributes in Realm element that need to be modified:

connectionURL – This is the url to the LDAP server

connectionName – User name to connect to the AD server.

connectionPassword – User password to connect to the AD server.

userPattern – path and pattern to the users

roleBase – path to root where groups reside. Groups must have a common OU to be included in the role base but can be is sub directories under this specified root

roleSubtree – attribute to enable searches in sub groups

roleName – attribute in AD of the Groups that should be included

roleSearch – attribute in the groups specifying the user. The {0} is used as a wild card to indicate all users in those groups

Once the configuration is set restart the server and log in as the AD user with the value that is placed in as the cn value (the cn may be the full name) and the AD password.

Complex Example

Requirements

  • Customer wants to use login name, instead of name, last name combination. Implementation of sAMAccountName.
  • Users are created in different OUs, i.e. location or department based AD structure. i.e. MyOrganization, YourOrganization, Accounting, HR. etc
  • Customer has sub domain. Users and groups are defined under this sub domain such as user@MySubDomain.MyDomain.com. If this user is located in Users group inside Accounting organizational unit, it would be equal toCN=user,OU=Users,OU=Accounting,MySubDomain,DC=MyDomain,DC=com

server.xml configuration:

        <Realm   className="org.apache.catalina.realm.JNDIRealm"
                connectionURL="ldap://MyServer.MySubDomain.MyDomain.com:389"
                connectionName="CN=Ephesoft_serviceAccount,OU=Service Users,OU=Users,OU=MyDepartment,OU=MyOrganization,DC=MySubDomain,DC=MyDomain,DC=com"
                connectionPassword="**********"
                userBase="DC=MySubDomain,DC=MyDomain,DC=com"
                userSearch="(&(objectClass=user)(sAMAccountName={0}))"
                userSubtree="true"
                roleBase="DC=MySubDomain,DC=MyDomain,DC=com"
                roleSubtree="true"
                roleName="cn"
                roleSearch="(&(objectClass=Group)(member={0}))"
                referrals="follow"/>

user-connectivity.properties configuration:

user.msactivedirectory_url=ldap://MyServer.MySubDomain.MyDomain.com:389
user.msactivedirectory_config=com.sun.jndi.ldap.LdapCtxFactory
user.msactivedirectory_context_path=OU=Ephesoft,OU=Groups,OU=MyDepartment,OU=MyOrganization;;OU=YourDepartment,OU=MyOrganization
user.msactivedirectory_domain_component_name=MySubDomain,dc=MyDomain
user.msactivedirectory_domain_component_organization=com
user.msactivedirectory_user_name=CN=Ephesoft_serviceAccount,OU=Service Users,OU=Users,OU=MyDepartment,OU=MyOrganization,DC=MySubDomain,DC=MyDomain,DC=com
user.msactivedirectory_password=************

Authorization of Ephesoft URLs

Ephesoft has several URLS such as

  • BatchList.html
  • BatchClassManagement.html
  • BatchInstanceManagement.html
  • ReviewValidate.html
  • WebScanner.html
  • Reporting.html

Administrators can authorize access to these URLs using group/role names defined in Tomcat, LDAP and MS Active Directory. Web.xml can be found here: *{EPHESOFT_ROOT_DIR}\WEB_INF\web.xml By Default all URLs authorized by all groups by using “*” in the auth-constrain node:

		<auth-constraint>
			<role-name>*</role-name>
		</auth-constraint>

To authorize a specific security role, LDAP container), administrators should modify the role-name node.

Examples: 1) to allow a role to access BatchInstanceManagement.html(role taken here admin):

   <security-constraint>
         <web-resource-collection>
               <web-resource-name>batch instance management</web-resource-name>
               <url-pattern>/BatchInstanceManagement.html</url-pattern>
               <http-method>GET</http-method>
               <http-method>POST</http-method>
         </web-resource-collection>
         <auth-constraint>
               <role-name>admin</role-name>
         </auth-constraint>
   </security-constraint>

Here we have allowed the role by mentioning it in the auth-constraint tag.

2) To allow multiple roles to access BatchInstanceManagement.html do the following configuration(roles taken here are role2 and admin):

       
<security-constraint>
         <web-resource-collection>
               <web-resource-name>batch instance management</web-resource-name>
               <url-pattern>/BatchInstanceManagement.html</url-pattern>
               <http-method>GET</http-method>
               <http-method>POST</http-method>
         </web-resource-collection>
         <auth-constraint>
               <role-name>role2</role-name>
               <role-name>admin</role-name>
         </auth-constraint>
   </security-constraint>

Here the <Security-role> tag need not to be modified. It can remain as it is with a single entry (*) allowing all groups. However it may give warnings if security-role tag is not mapped to groups individually. These warnings can be eliminated by providing mapping for roles in <security-role> tag.

      <security-role>
            <role-name>*</role-name>
      </security-role>




[/vc_column_text][/vc_column][/vc_row]