.. include:: /includes.rst.txt

.. comments - headings

   # with overline, for parts
   * with overline, for chapters
   = for sections
   - for subsections
   ^ for subsubsections
   " for paragraphs
   * for H5
   + for H6

.. _ldap_configuration:

LDAP Configuration
------------------

This section describes how to use the EDG server with LDAP authentication.

Integration Instructions
^^^^^^^^^^^^^^^^^^^^^^^^

Authentication is the process by which users log on to EDG. 
It is possible, but not advised, to run EDG without authentication. 
In this case, all users get full administrative privileges.

EDG uses the Tomcat web-app server for authentication. 
This is intended to help implementation of policies such as single sign-on. 
EDG provides no further features for single sign-on. 
If this is a policy mandated for your environment, first find some other Java EE based service and understand which Web Application Server they are using, and how they authenticate users in accordance with the single sign-on policy. 
Then contact TopQuadrant with this information for advice as to how to configure EDG in a similar way.

This section provides instructions for integrating EDG with LDAP in Linux and Active Directory in Windows Server.

LDAP Configuration within Tomcat
""""""""""""""""""""""""""""""""

These instructions cover the configuration of LDAP within Tomcat. 
For any other web application server, there could be some differences. 

.. note:: The exact formats used will depend on your LDAP configuration. 
 Also, although the description below has a step to initiate an LDAP service, normally this is not required because you will be using a pre-existing LDAP service for configuring Tomcat and EDG.

Identifying/Creating a Group and at Least One User in That Group
****************************************************************

In the sample configuration routine shown below, we will set the security to permit a specific group to access EDG. 
This group needs a name, which is configured within LDAP. 
You may already have an appropriate group.

.. index:: pair: Configuring ; Tomcat LDAP

Configuring Tomcat to Use LDAP
******************************

Next, we need to configure tomcat to connect to LDAP. 
This is specified in this document: https://tomcat.apache.org/tomcat-8.5-doc/realm-howto.html#JNDIRealm

This step requires adding an entry to ``server.xml``, found in the ``conf`` folder for Tomcat. 
For our example, the entry is as follows:

::

 <Realm   className="org.apache.catalina.realm.JNDIRealm" debug="99"
    connectionURL="ldap://localhost:389"
    userPattern="uid={0},ou=people,dc=tqinc,dc=info"
    roleBase="ou=groups,dc=tqinc,dc=info"
    roleName="cn"
    roleSearch="(memberUid={1})"
    />

.. note:: In this expression, ``{0}`` and ``{1}`` both stand in for the username, but the actual expressions such as ``uid={0},ou=people,dc=tqinc,dc=info`` will be different depending on your LDAP service.

For reference, this is for group configuration that looks like this in LDAP:

::

 keefe@keefetq:~$ ldapsearch -xLLL -b "dc=tqinc,dc=info" -s sub "(memberUid=keefe)"
 dn: cn=acme,ou=groups,dc=tqinc,dc=info
 objectClass: posixGroup
 cn: acme
 gidNumber: 10001
 description: Group account
 memberUid: keefe

If your LDAP directory is setup in a straightforward way, it should be easy to modify the search expression appropriately. 
However, you may need assistance from someone who knows your LDAP system.

Three pieces of information are needed:

1. A base pattern to identify groups in LDAP, (in this case: ``ou=groups,dc=tqinc,dc=info``).

2. A property at which the rolename we will use in securing EDG may be found, in this case: ``cn``

3. A search filter that indicates role membership, in this case : ``(memberUid={1})`` where ``{1}`` is the username.

.. index:: pair: Configuring ; Active Directory in Tomcat

Active Directory Integration within Tomcat
""""""""""""""""""""""""""""""""""""""""""

.. note:: The exact format depends on your LDAP configuration.

Populate LDAP
*************

The security to permit a specific group of users to must be set to access EDG. 
This group needs a name, which is configured within LDAP. You may already have an appropriate group.

1. Create TopBraid EDG group(s) and associate users with this group in Active Directory using the wizard. 
   You will need at least one for administrators and one for non-administrators. 
   You can have more if needed. 

Configuring Tomcat to Use LDAP for Active Directory
***************************************************

Next, configure tomcat to connect to LDAP. 
This is specified in this document: https://tomcat.apache.org/tomcat-8.5-doc/realm-howto.html#JNDIRealm

It requires adding an entry to ``server.xml``, found in the ``conf`` folder for Tomcat. 
For our example, the entry is as follows:

::

 <Realm className="org.apache.catalina.realm.JNDIRealm"

 		 connectionURL="ldap://localhost:3268"
 		 authentication="simple"
		 referrals="follow"

		 connectionName="jeremy@tblive.tqinc.info"
		 connectionPassword="enter password here"

 		 userSearch="(sAMAccountName={0})"
		 userBase="CN=Users,DC=tblive,DC=tqinc,DC=info"
		 userSubtree="true"

		 roleSearch="(member={0})"
		 roleName="cn"
		 roleSubtree="true"
		 roleBase="CN=Users,DC=tblive,DC=tqinc,DC=info"

		 debug="99"
 	 />

Inside of the LDAP Engine element
*********************************

This section provides a background and overview of LDAP in case you are unfamiliar. 
Use this as reference when working with your LDAP team at your organization. 
Typically this will all be configured and you will only need to request new groups are created for TopBraid EDG users.

In the *userSearch* expression, ``{0}`` stands for the username as typed by the end-user, whereas in the *roleSearch* expression, ``{0}`` stands for the distinguished name found from the user look up. 
(These are written literally as ``{0}`` in the server.xml file), but the actual expressions such as ``(sAMAccountName={0})`` and ``CN=Users,DC=tblive,DC=tqinc,DC=info`` will be different depending on your LDAP service. 
With Active Directory, ``(sAMAccountName={0})`` and ``roleSearch="(member={0})"`` should generally be correct.

If your LDAP directory is setup in a straightforward way, it should be easy to modify the search expression appropriately. 
However, you may need assistance from someone who knows your LDAP system.

Three pieces of information are needed:

1. A base pattern to identify groups in ldap, (example: ``CN=Users,DC=tblive,DC=tqinc,DC=info``).

2. A property at which the rolename we will use in securing EDG may be found, in this case:cn

3. A search filter that indicates role membership, in this case : ``(member={0})`` where ``{0}`` is the distinguishedName (and ``{1}`` is the username).


LDAP Servers (Service Providers)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The preceding LDAP sections configure EDG to use of LDAP for authentication: user login identity and roles. 
To further configure EDG for using additional LDAP information, e.g., email, see :ref:`ldap_servers`.