Configure Active Directory with the Global Catalog Service port

The Global Catalog service enables you to use the root domain (Domain components DC only) as the user base and role base for authentication with LDAP/Active Directory. You can use a single <Realm> configuration to handle all authentication and authorization requests, and you only need to work with the root domain.

Use port 3268 for the global catalog of the working Active Directory. (Active Directory uses various ports for other purposes.)

When Active Directory functions as a simple LDAP service, it cannot handle root domain search requests. Root domain searches in Active directory return referrals to the root components that can only be handled by the global catalog service, not by the standard LDAP service. There may also be ambiguity when more than one user has the same CN. To address these issues, see Resolving ambiguous user accounts.

Follow these steps to configure your system.

Modify the user-connectivities.properties file located in <Transact Install Folder>\Application\WEB-INF\classes\META-INF\dcma-user-connectivity.

Change the following settings with the correct domain and connection information.

# LDAP/MS Active Directory

user.connectivity_url=ldap://<Servername/IP>:3268
user.connectivity_config=com.sun.jndi.ldap.LdapCtxFactory
user.connectivity_domain_component_name=test,dc=ephesoft
user.connectivity_domain_component_organization=com
user.connectivity_username=cn=User,dc=test,dc=ephesoft,dc=com
user.connectivity_password=P@ssw0rd
# This Property defines which type of connectivity is used

If your configuration involves a sub-domain, enter the description in the following format: user.connectivity_domain_component_name=sub,dc=domainname

Enable the Active Directory Authentication Feature by changing the user.connection setting as shown.

# This Property defines which type of connectivity is used
# 0 = LDAP
# 1 = MS Active Directory
# 2 = Tomcat
user.connection=1

Change the LDAP: Normal LDAP service to search on the root domain without further configuration:
- Set user.ldap_user_base to empty.
- Set user.ldap_group_base to empty.
Set user.msactivedirectory_context_path to empty.
Set user.msactivedirectory_group_search_filter to a single filter value.

This setting will be in sync with the setting in Server.xml.

The following is an example of the user-connectivity.properties file:

# LDAP/MS Active Directory

user.connectivity_url=ldap://<Servername/IP>:3268
user.connectivity_config=com.sun.jndi.ldap.LdapCtxFactory
user.connectivity_domain_component_name=test,dc=ephesoft
user.connectivity_domain_component_organization=com
user.connectivity_username=cn=User,dc=test,dc=ephesoft,dc=com
user.connectivity_password=P@ssw0rd
# This Property defines which type of connectivity is used
# 0 = LDAP
# 1 = MS Active Directory
# 2 = Tomcat
user.connection=1
# Set this for LDAP Connectivity
user.ldap_user_base=
user.ldap_group_base=
#This Attribute is added so as to make search of groups in LDAP/AD configurable,by default its cn(commonName) is returned
user.connectivity_groupSearchAttributeFilter=cn
#This Attribute is added to make search of Users (Organisational Unit) in LDAP/AD configurable,by default its cn
user.connectivity_userSearchAttributeFilter=cn
#Set this for MS Active Directory
user.msactivedirectory_context_path=
# 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=ephesoft*)
# Tomcat Connectivity
user.tomcatUserXmlPath=C:\\Ephesoft\\JavaAppServer/conf/tomcat-users.xml
#Switch To display user’s Full name on the apptication UI.
# Default value is OFF.
# 1 = ON.
fullname.display=1

Change the following attributes:

user.connectivity_url: URL to the AD/LDAP server.
user.msactivedirectory_context_path: Path to the room OU where groups reside. Multiple locations can be specified with a ";;" delimiter (example: OU=Internal Groups;;OU=Contractors).
user.connectivity_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.connectivity_domain_component_organization: Root DC of the AD store (typically "com").
user.connectivity_username: User name to connect to the AD server.
user.connectivity_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: Set between 0–2 to enable the AD, LDAP or Tomcat configuration in order to authenticate users.

Modify the <Realm> settings in the server.xml file located in <Transact Install Folder>\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})"/>
```
Change the following attributes:
- connectionURL: This is the URL to the LDAP server.
- connectionName: User name to connect to the Active Directory server.
- connectionPassword: User password to connect to the Active Directory server.
- userPattern: Path and pattern to the users.
- roleBase: Path to the root where groups reside. Groups must have a common OU to be included in the role base, but can be sub-directories under this specified root.
- roleSubtree: Attribute to enable searches in sub groups.
- roleName: Attribute in Active Directory 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.
Here is an example of <Realm>:
```
connectionURL="ldap://192.1.0.2:3268"
connectionName="cn=User1,dc=test,dc=ephesoft,dc=com"
connectionPassword="P@ssw0rd"
   userBase="DC=test,DC=ephesoft,DC=com"
	  userSearch="(sAMAccountName={0})"
	  userSubtree="true"
	  referrals="follow"
	  roleBase="DC=test,DC=ephesoft,DC=com"
	  roleName="cn"
	  roleSubtree="true"
	  roleSearch="(member={0})"
```
The default <Realm> settings in the server.xml file are not the same as the <Realm> configuration mentioned above. If you use the default settings, modify them accordingly.
Modify the application.properties file located in the \Ephesoft\Application\WEB-INF\classes\META-INF folder.
Set the following property:
```
update_super_admin_group=true
```
Set this property to the Active Directory group that should have Super Admin rights.
```
user.super_admin=Administrators
```
The group name you provide for user.super_admin will have Super Admin access to all Transact functionality. Super Admin users can assign roles to users in other groups in Transact by selecting System Configuration > Access Manager.

Note the following:
- The Super Admin user must be present in the correct group that you have defined in the application.properties file in user.super_admin group. If this is not the case, an error message will indicate that you are not authorized to view a page.
- Transact does not support nested groups in Active Directory.
- If the Active Directory user that you are using for the user-connectivity.properties and the server.xml has a different CN from the sAMAccountName in the AD user configuration, set the value for user.connectivity_userSearchAttributeFilter= to sAMAccountName. (Example: user.connectivity_userSearchAttributeFilter=sAMAccountName)

Resolving ambiguous user accounts

If there are multiple users with the same name (as defined by CN), it could cause ambiguity when attempting to authenticate an account. Transact cannot handle the client logon request because it depends on the LDAP and Active Directory implementations on a specific server.

Consider this example of three users with the same CN, but different groups:

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

The user you want to log on is CN=admin, OU=management, DC=ephesoft, DC=com. So, in server.xml, you configure <Realm> as follows:

userBase="DC=ephesoft,DC=com"
userSearch="(CN={0})"

The result is that it matches the first entry, CN=admin, OU=sales, DC=ephesoft, DC=com, but the user you want is the third entry, CN=admin, OU=management, DC=ephesoft, DC=com.

To avoid this issue, modify userSearch to enable it to identify a unique user. Some suggestions:

Use a unique parameter such as (sAMAccountName={0}). Have users enter the value for that unique parameter into username while logging in to the application.
Extend search parameters, such as CN (common name), first name, and last name.