Verifing Users in DataONE
=========================

During the Member Node (MN) registration process, we require that the Distinguished Name (DN) listed in the `Node.contactSubject`_ field of the MN Node document passed into the `CNRegister.register()`_ API call is verified in the Coordinating Node Account Registry before the node registration can succeed.  This document outlines how to verify a user DN, and gives an example using Apache Directory Studio as the LDAP client application making the change.

Setting up an LDAP client
-------------------------

For security reasons, the LDAP service running on each Coordinating Node is firewalled except for connections among the three CNs in an environment.  To connect with a client application like `Apache Directory Studio`_, you need to 1) establish an SSH tunnel to one of the CNs in the environment, and 2) configure the client application to connect to the LDAP service using manager credentials.

Establishing an SSH tunnel
--------------------------

Use the ``ssh`` command to establish a tunnel, choosing an unpriveleged local port (like 3890) to be forwarded to port 389 on the CN:

::

    $ ssh -L3890:localhost:389 cn-stage-ucsb-1.dataone.org

Configuring the client application
----------------------------------

Create a new connection in Apache Directory Studio, and set the properties of the connection according to the environment you are connecting to.  For instance, the screenshots below show the properties for a connection named ``D1TestCNsViaLocalhost``:

.. figure:: images/ads_connection_properties_1.png

    Figure 1: Example Network Properties connecting to localhost on port 3890
 
.. figure:: images/ads_connection_properties_2.png

    Figure 2: Example Authentication Properties connecting as cn=admin,dc=dataone,dc=org

For the authentication password above, the password is cached in either the `SystemPW.txt.gpg`_ file for test installations or in the `ProductionPW.txt.gpg`_ file for production installations. Decrypt these files with your gpg key.

Connect to the LDAP service
---------------------------

Open the connection to the LDAP service, and navigate to into the Directory Tree (DIT) under the ``dc=cilogon,dc=org`` branch.  If the Directory Tree doesn't show the branches (which seems to be a bug in Apache Directory Studio), right click on the ``Root DSE`` folder and choose the ``Go to DN ...`` menu item, as shown in Figure 3.  You can then type in the ``dc=cilogon,dc=org`` branch as shown in Figure 4.  Once the tree shows up, navigate to the entry you want to edit, shown in Figure 5.  In this case, set the ``isVerified`` attribute to ``TRUE``.

.. figure:: images/ads_connection_properties_3.png

    Figure 3: If needed, use the ``Go to DN ...`` menu item.
 
.. figure:: images/ads_connection_properties_4.png

    Figure 4: If needed, manually provided the DN location

.. figure:: images/ads_connection_properties_5.png

    Figure 5: Editing the LDAP entry for a specific user DN

Checking for correct replication
--------------------------------

WHen any entry on one of the CNs gets modified, it should automatically replicate to the LDAP services on the other CNs within the environment.  However, we've seen some issues with the OpenLDAP ``syncrepl`` function, and there are times when the entries do not propogate.  To check this, open an ssh connection to each CN, and query the LDAP service using the ``ldapsearch`` command.  In the example below, we're using tmux to connect to all 3 CNs at once.

.. figure:: images/ads_connection_properties_6.png

    Figure 5: Use ``ldapsearch`` to ensure entries updated on each CN
    
Troubleshooting LDAP inconsistencies
------------------------------------

If the output of the above commands don't match (for instance, one or two of the CNs have a value of ``false`` for the ``isVerified`` attribute), it may be caused by network disruptions between the LDAP servers.  In severe cases, the LDAP service has stopped trying to replicate after too many retries, or potentially hung retries.  In this case, you may need to restart the ``slapd`` service on the out-of-sync CNs.  Be aware that when doing this, it may take up to 30 minutes for ``slapd`` to stop cleanly, and then restart.  This may be due to the daemon waiting for outstanding network requests to time out.  It's best to tail the system log file for ``slapd`` entries to confirm that the service has stopped cleanly before restarting it.  Don't send any abrupt signals to the process like ``kill -9`` since that has proven to corrupt the LDAP database in the past.


.. _SystemPW.txt.gpg: https://repository.dataone.org/documents/Projects/cicore/operations/source/pw/
  
.. _ProductionPW.txt.gpg: https://repository.dataone.org/sysadmin/PW/

.. _Apache Directory Studio: "https://directory.apache.org/studio

.. _Node.contactSubject: https://releases.dataone.org/online/api-documentation-v1.2.0/apis/Types.html#Types.Node.contactSubject

.. _CNRegister.register(): https://releases.dataone.org/online/api-documentation-v1.2.0/apis/CN_APIs.html#CNRegister.register