= LDAP UI Installation =

Native LDAP store doesn't come with a GUI. Therefore, as administrators we may have to provide a nice user interface to our users. This UI should have the capability of changing details of users password resets, etc. To do these actions there are lot of open source packages as well as commercialized products.

On this tutorial we will go through two UI setups that will focus on different outputs.

== Apache Directory Studio (For Admins) ==

* Download and install
   The latest version of Apache Directory Studio can be downloaded to your host machine from the Apache Directory Studio Downloads page, at this address : http://directory.apache.org/studio/downloads.html

   Installation steps https://directory.apache.org/studio/users-guide/apache_directory_studio/download_install.html

   Once the installation succeeds open the Apache Directory Studio.

   Creating the ldap connection:
{{{
Go to File --> new --> ldap browser --> ldap connection --> next
}}}

   Enter your deatils:

{{{
Connection Name: LDAP Server
Hostname: ldap://idp.instXY.ac.lk
port: 389
Encrypted Method: Use STARTTLS
Provider: Apache Directory LDAP Client API
}}}

`Next`

{{{
Authentication Method: Simple Authentication
Bind Dn: cn=admin,dc=thilinapathirana,dc=xyz
Bind Password:
}}}


   Click `Check Authentication` to make sure your credentials work. For the first time it ask to trust the self signed certificate.

   Select `Always trust this Certificate` and click `OK`

   Then click `Finish`.

*  To connect, double click the connection just created from '''Connections''' list.

* Once connected you can browse through the directory using the LDAP Browser.

* When modifying entries you may use a ldif file or the GUI.

* Using GUI to create an OU:
  - Select '''root location''' for the OU (eg. dc=instXY,dc=ac,dc=lk)
  - Select `New Entry` on '''Right click Menu'''
  - Then `Create entry from Scratch`  --> `Next`
  - Select `OrganizationalUnit` and click `Add` and `Next`
  - Type `OU` as the '''RDN''' and the desired value in-front of it, then click `Next` and `Finish`


* Adding a User Group
  - Select '''root location''' for the OU (eg. ou=Group,dc=instXY,dc=ac,dc=lk)
  - Select `New Entry` on '''Right click Menu'''
  - Then `Create entry from Scratch`  -->  `Next`
  - Select `groupofNames` and click `Add` and `Next`
  - Type `CN` as the '''RDN''' and the desired value in-front of it and then click `Next`
  - You will prompt with a '''user add window''' as DN Editor. Select a user from browser and click `OK`


* Adding a new User
  - Select '''root location''' for the OU (eg. ou=People,dc=instXY,dc=ac,dc=lk)
  - Select `New Entry` on '''Right click Menu'''
  - Then `Create entry from Scratch`  -->  `Next`
  - Select `inetOrgPerson` and click `Add`
  - Select `eduPerson` and click `Add` and `Next`
  - Type `uid` as the '''RDN''' and the desired username value in-front of it and then '''Next'''
  - Enter desired values for '''cn''' (First Name) and '''sn''' (last Name) 
  - Enter `new attribute` from '''right click menu'''  as `userPassword` and click finish. when it asks, enter the new users password and select '''Plaintext''' as the hash method and click '''OK'''
  - You may add any other attribute as well.
  - Then click finish


More documentation can be found on https://directory.apache.org/studio/users-guide/


== Keycloak Server (For End Users) ==

Keycloak is an open source identity and access management solution, we will use keycloak only to provide a friendly self care portal to users allowing services such as password resets.

We will install Keycloak in your idp vm for the lab purpose but it is recommended to install it on a separate server with at least 4GB RAM for production environment.

* Install Dependancies
   * Become the root user by `sudo su`
   * `apt-get install vim default-jdk`
   * Define the constant `JAVA_HOME` inside /etc/environment:
      * `update-alternatives --config java`
        (copy the path without /bin/java)
      * `vim /etc/environment` and include
       * `JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64`
      * `source /etc/environment`
    * `export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64`


* Download Keycloak and extract:
   * 
   {{{
        wget https://downloads.jboss.org/keycloak/4.4.0.Final/keycloak-4.4.0.Final.tar.gz
   }}} 
   {{{
        tar -xvzf keycloak-4.4.0.Final.tar.gz
    }}}

* Go to the executable directory:
   {{{
     cd keycloak-4.3.0.Final/bin/
   }}}
 
* Create Initial Admin User
   {{{
     ./add-user-keycloak.sh -r master -u adminiam -p Iam@2018
    }}}

* Edit listning interface:
   {{{
       vim standalone/configuration/standalone.xml
   }}}
   look for the `interfaces` XML block   
   {{{#!xml
          <interfaces>
                  <interface name="management">
                      <inet-address value="${jboss.bind.address.management:127.0.0.1}"/>
                  </interface>
                  <interface name="public">
                      <inet-address value="${jboss.bind.address:127.0.0.1}"/>
                  </interface>
          </interfaces>
   }}}

  Change IP address `127.0.0.1` to `0.0.0.0` allowing traffic from outside.

* Start the server
{{{
     ./bin/standalone.sh &
}}}

* Now you should be able to access the server through your browser by accessing: https://idp.instXY.ac.lk:8443/auth/admin

* Log in to the master admin console. This will provide full privileged access to the system.

* Create your own realm (domain)
   * From the Master drop-down menu, click Add Realm.
   * Put '''instXY''' as the Name and `Add`
   
   From here onwards, make sure you select instXY from the master menu when doing changes.

* Customizing Realm
   * Go to your "Realm Settings"
   * On '''General''' tab
      * Enter display name as '''Institute XY'''
      * Enter HTML display name as `<span><img src="URL-TO-YOUR-LOGO"></span>` and SAVE
   * On Login tab
      * Switch '''on''' `Forgot password`
      * Switch '''off''' `Login with email`  and SAVE

* Connect your ldap instance:
   * Go to '''User Federation''' and select '''ldap''' from add provider drop down menu.
      * Mark Edit Mode as '''WRITEABLE'''
      * Sync Registrations as '''ON'''
      * Vender as '''Other'''
      * User Object Classes as `inetOrgPerson, organizationalPerson, eduPerson, extensibleObject`
      * Connection URL as `ldap://idp.instXY.ac.lk:389`
      * Users DN as `ou=people,dc=instXY,dc=ac,dc=lk`
      * Authentication type as '''simple'''
      * BIND DN as `cn=admin,dc=instXY,dc=ac,dc=lk`
      * Bind Credential as `iam@2018`
      * Search Scope as '''subtree'''
      * Periodic Full Sync as '''ON'''
      * Periodic Changed Users Sync as '''ON'''
      * Save
   For the first time you will need to click '''Synchronize All Users''' 

* Map User Attributes

   You have to map user attributes that are essential in password resetting. When a user clicks forgot password link it will send a reset link to a working email. Keep in mind that the attribute `mail` should be the key attribute for mapping the ldap user for various outside services. Therefore it should be something in the format `user@instXY.ac.lk` and it should not be allowed to be changed by the users. Because of this, we will use ldap attribute `email` to fill in the alternate email of the user which is used to send the reset requests. 

   To do this you need to edit the ldap email mapper from the settings.
   
   Go to `User Federation --> ldap --> Mappers` and select email

   Change the value of '''LDAP Attribute''' to '''email''' and Save.

   On your production servers you need to configure your email server settings on `Realm Settings --> Email`

Ask Users to login to https://idp.instXY.ac.lk:8443/auth/realms/instXY/account change there user profile and details (Change instXY in the url as per your realm name)

* Usage of OTP.

   Users can utilize the function OTP from their profile page. They may use any OTP software such as Google Authenticator, Authy, etc. This will add additional security to the password reset process.
   

> For further customization you may consult keycloak official guides from https://www.keycloak.org/documentation.html