Last Updated on

Integrating Ephesoft with Active Directory

This wiki article focus on providing detailed explanation on how to integrate Ephesoft with Active Directory. This article focuses on detailed explanation of each property used in order to successfully configure Ephesoft with Active Directory.

In Ephesoft we basically have to focus on 3 properties file mentioned as below:

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

What is required to configure 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 any knowledge on how your Active Directory looks you will not able to configure the Ephesoft configuration files.

We expect that users are having at-least below knowledge of their Active Directory:

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

 


Sample Directory Structure Example to be used to Configure Active Directory

In this section we will go through an example of directory structure which will help us to configure Ephesoft to integrate 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 root domain name is “com” and it is having a sub-domain called “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 OU called GROUPS AND USERS.
  • GROUPS OU consist of Groups / Roles in Active Directory. We have 3 groups with the name Ephesoft-Administrator, Ephesoft-SystemAdministrator and Ephesoft-Users
  • USERS OU consist of Users in the 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 we distinguish roles on the basis of below:

  • 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 have 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 the Active Directory.
  • Below is a sample screenshot of Realm Setting 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 which 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 port in case of Active Directory needs to be 3268 (Also called Global Catalog Port) or 3269 (If Active Directory is over SSL).
  • connectionName: We need to define the Distinguished Name of any user who exist in the Active Directory. In the screenshot above CN=aj,OU=USERS,OU=EPHESOFT,DC=ephesoft,DC=com means that 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 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 the Organizational Units.
  • roleName: the attribute in a role entry containing the name of that role. In above example value of 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 member property of 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 needs to be fetched from the Active Directory.
  • Below is an example for configuring 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 port in case of Active Directory needs to be 3268 (Also called Global Catalog Port) or 3269 (If Active Directory is over 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 value cn. This property will look at the cn property in Active Directory and according will pick the Group / Role name defined in this property.
  • user.connectivity_userSearchAttributeFilter: Usually set to value cn or sAMAccountName. This property will look at the cn or sAMAccountName property from the Active Directory. This needs to be set according to the value set in  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’s then we can separate them using double semicolon(;;)
  • user.msactivedirectory_group_search_filter: We define the pattern to only pick the groups which matches 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 the pages of the Ephesoft User Interface, Access to all Batch classes and access to all batch instances. Only this user can provide access to other groups and assign roles to other groups at batch class level.
  • Access Manger UI where access control can be assigned to other groups

 

  • Roles Column in Batch Class Management Screen where to provide Access control at Batch Class and Batch Instance Level. As you can see in the below screenshot Users in Ephesoft-Administrator group only will be able to view BC3A batch class and its associated Batch Instances.

 

Was this article helpful to you?

Abhishek Jain