Integrating Ephesoft with Active Directory

Integrating Ephesoft with Active Directory

This article explains how to integrate Ephesoft with Active Directory and provides detailed description for each property used in order to successfully configure Ephesoft with AD.

In Ephesoft Transact, we basically have to focus on 3 properties files mentioned below:

  • server.xml
  • user-connectivity.properties
  • application.properties

What is required for configuring Ephesoft with Active Directory ?

In order to successfully integrate Ephesoft with AD, it becomes essential to understand the directory structure first. If you do not have required information about your Active Directory, you will not able to configure the Ephesoft configuration files.

We expect the users to know at least the following details about their Active Directory:

  • A user which exists in the directory.
  • Password of the user as mentioned above.
  • Difference between domain controllers, Organizational Units, Groups and Users.
  • Information on where Users exist in Active Directory.
  • Information on where Groups exist in Active Directory.
  • Users are mapped with respective groups.

 


Sample directory structure to be used for configuring Active Directory

In this section we will go through a sample directory structure which will help us to configure Ephesoft for integration with Active Directory.

After looking at the below AD structure we will understand the information required in order to configure Ephesoft with Active Directory.

  • We have a domain controller with a name com.ephesoft where the root domain name is “com” and the sub-domain name is “ephesoft”. These domains are denoted with abbreviation “dc”.
  • There can be more than 1 sub-domain as well like com.ephesoft.support
  • In the below directory structure we have an Organizational Unit (“OU”) called EPHESOFT under which we further have two OUs called GROUPS and USERS.
  • GROUPS OU consists of Groups / Roles in Active Directory. We have 3 groups with the name Ephesoft-Administrator, Ephesoft-SystemAdministrator and Ephesoft-Users
  • USERS OU consists of Users in Active Directory. We have 2 users with the name aj and ephesoft.
  • We know that user “aj” is added to the group Ephesoft-SystemAdministrator.

We now have all the required information in order to configure Active Directory.


Understanding Roles in Ephesoft

In Ephesoft Transact, we distinguish the roles on the following basis:

  • Super Administrator : A super administrator has complete access to the Ephesoft user interface.
  • Administrator: An administrator doesn’t have access to System Configuration user interface.
  • Operator: An operator usually has access to Non-Admin user interfaces like Batch List, Review Validate etc.

Configuring Ephesoft Server.xml

  • In server.xml file we define information about Active Directory and configuration in this file helps to authenticate the users with Active Directory.
  • Below is a sample screenshot of realm settings in server.xml which is used to connect to Active Directory and tries to authenticate users.

  • className: This needs to be set to org.apache.catalina.realm.JNDIRealm. This refers to JNDIRealm class in Tomcat.
  • connectionURL: We need to define the URL of the Active Directory server. It is of the form of ldap://<IP,DNS,FQDN>:<PORT> where the port in case of Active Directory needs to be 3268 (also called the Global Catalog Port) or 3269 (if Active Directory is configured with SSL).
  • connectionName: We need to define the Distinguished Name of any user who exists in Active Directory. In the screenshot above CN=aj,OU=USERS,OU=EPHESOFT,DC=ephesoft,DC=com means that the user with the name “aj” exists in OU called “USERS” which is under “ephesoft” sub-domain and “com” root-domain. We can also define the connectionName here using naming convention like aj@ephesoft.com
  • connectionPassword: We need to provide the password for the user defined in connectionName.
  • userBase: The relative path under which all the users’ information will be located. This attribute defines where to look for a user. In our example above we are looking for users directly under our sub-domain. Therefore it will look for the user under the sub-domain as well as in all the Organizational Units as well.
  • userSearch: This is the pattern specifying the Active Directory search filter to use after substitution of the username. Possible values are “(sAMAccountName={0})” or “cn={0}”. If we are using sAMAccountName then it will look for the value in sAMAccountName property of Active Directory and if we are using cn={0} then it will look for value in cn property in Active Directory.
  • roleBase: The relative path under which all the roles information will be located. This attribute defines where to look for a role corresponding to a user. In this example we are searching for all Roles / Groups under sub-domain “ephesoft” as well as in all Organizational Units.
  • roleName: The attribute in a role entry containing the name of that role. In above example, the value of the cn attribute in Active Directory will be checked.
  • roleSearch: The LDAP search filter for selecting role entries. It optionally includes pattern replacements “{0}” for the Distinguished Name. In above example, the member property of the user in Active Directory will be looked up.
  • userSubtree: The search scope. Set to true if you wish to search the entire sub tree rooted at the userBase entry.
  • roleSubtree: The search scope. Set to true if you wish to search the entire sub tree rooted at the roleBase entry.

Configuring Ephesoft user-connectivity.properties

  • user-connectivity.properties file is configured to take care of the authorization part. We can apply limitations on what groups / roles need to be fetched from the Active Directory.
  • Below is a sample configuration in the user-connectivity.properties file

  • user.connectivity_url: We need to define the URL of the Active Directory server. It is of the form of ldap://<IP,DNS,FQDN>:<PORT> where the port in case of Active Directory needs to be 3268 (also called Global Catalog Port) or 3269 (if Active Directory is configured with SSL).
  • user.connectivity_domain_component_name: We need to put in the sub-domain information. If we have more than one sub-domain like com.ephesoft.support then we need to define convention for user.connectivity_domain_component_name=support,dc=ephesoft.
  • user.connectivity_domain_component_organization: We need to give the root level domain name.
  • user.connection: This property needs to be set to 1 if we need to use AD.
  • user.ldap_user_base: This is LDAP related property and we do not need to define any value for this property if we are using Active Directory.
  • user.ldap_group_base: This is LDAP related property and we do not need to define any value for this property if we are using Active Directory.
  • user.connectivity_groupSearchAttributeFilter: Usually set to the value cn. This property will look at the cn property in Active Directory and accordingly will pick the Group / Role name defined in this property.
  • user.connectivity_userSearchAttributeFilter: Usually set to the value cn or sAMAccountName. This property will look at the cn or sAMAccountName property from Active Directory. This needs to be set according to the value set in the userSearch property in server.xml.
  • user.msactivedirectory_context_path: We define the relative path where the groups exist. If groups exist in more than one OU, we can separate them using double semicolon(;;)
  • user.msactivedirectory_group_search_filter: We define the pattern to only pick the groups which match this pattern. Please note that if the name of super admin group doesn’t match the pattern, then we need to add the name of the group here. Example: (|(cn=EphesoftSupport*)(cn=Ephesoft-SystemAdministrator)). This pattern will pick all groups starting with EphesoftSupport and followed by anything and since we have a super admin group which doesn’t match this pattern we have added Ephesoft-SystemAdministrator separately in this filter.

Note: user.msactivedirectory_context_path and user.msactivedirectory_group_search_filter can be used together as well to further limit the GROUPS


Configuring Ephesoft application.properties

  • This file is used to set the super admin group details.
  • Two properties that require change is user.super_admin where we define super admin groups and update_super_admin_group where we will need to change the flag to true.

Access Management on Ephesoft User Interface

  • Super User which is a part of Super User Group has access to all pages of the Ephesoft user interface, all batch classes and all batch instances. Only this user can provide access to other groups and assign roles to other groups at the batch class level.
  • Access Manager UI where access control can be assigned to other groups

 

  • Roles Column in the Batch Class Management screen where to provide access control at the batch class and batch instance level. As you can see in the below screenshot, the Users in Ephesoft-Administrator group will be able to view only BC3A batch class and its associated batch instances.

 

Configuring Active Directory:

There are two support methods that can be used to configure AD connection:

1. Using the Global Catalog Service Port (Recommended)

2. Using the default LDAP Service Port