LDAP User Access

The is an authentication mechanism which authenticates users against an openLDAP server

This user access mechansim is implemented by the I2CE_UserAccess_LDAP class.

Configuration

To use the default user authentication, you need to enable the module and set an initialization string.

Enabling the Module

To enable, just make sure you have: <source lang='xml'>

<requirement name='UserAccess_LDAP'>
  <atLeast version='4.0'/>
  <lessThan version='4.1'/>
</requirement>

</source>

Initialization String

The initialization string is sent to I2CE::initialize() in the index.php as the fourth argument, $user_access_init. This string must be prefixed with the 'LDAP://. What follows take any of the following formats:

• null: The is the default value and means that we use the default DN (distinguished name) for querying and authenticating users
• a JSON encoded string: The data to is a JSON enocode string of optional configuration value for the user access. The JSON encoded data has the following keys:
  • host: Defaults to 'localhost' The hostname where the openLDAP server lives
  • port: The port openLDAP is listening on. Defaults to 389
  • ldap_user: The user to attempt to bind the ldap connection to. Defaults to empty in which case we do an anonymous connection
  • ldap_pass: The password to attempt to bind the ldap connection with. Defaults to empty.
  • dn: The DN used to query against. Defaults to 'dc=localhost'
  • app: The application name used to check for user roles in. If not set, it will use the site module's name
  • people: The qualifier to query people against. Defaults to 'ou=People'.
  • roles: The qualifier to query user roles against. Defaults to 'ou=Application'.
  • encrypt: how the password is stored on the openLDAP server. Default is SSHA. Possible values are:
    • 'plaintext'
    • 'SHA'
    • 'SSHA'
  • salt: the salt to use for encryption (if needed). Defaults to none.
  • p_details: associative array of the user details that are querriable against ou=People.Defaults as follows:
    • firstname:givenName
    • lastname:sn
    • email:email
  • p_detail_names: associative array of the display names of user details that are querriable against ou=People.Defaults as follows:
    • firstname:Firstname
    • lastname:Surname
    • email:E-mail
  • a_detail_s: associative array of the user detail display names that are querriable against ou=Application.Defaults to:
    • locale:Preferred Locale
  • appid: the query used to get the user's id for the application. Defaults to 'appid'
  • role: the query used to get the user's role for the application. Defaults to 'role'
  • can_change_pass: defaults to true
  • can_create_user: defaults to true
  • can_edit_user: defaults to true

For example:

LDAP://

would be a minimal initialization string needed to authenticate against. For the examples below, you would use:

 LDAP://{"dn": "dc=moh,dc=example,dc=org"}

LDAP Directory Structure

Example Entries

A user could be represented as:

   dn: uid=litlfred, ou=People, dc=moh,dc=example,dc=gov
   sn: Leitner
   givenName: Carl
   cn: Carl Leitner
   userPassword: {SSHA}DkMTwBl+a/3DQTxCYEApdUtNXGgdUac3
   email: cleitner@intrahealth.org

User roles be unique on the pair (username, software-component) and there may be software component specific information to share,

   dn: uid=litlfred, app=ihris-manage, ou=Application, dc=moh,dc=example,dc=gov
   role: hr_staff
   appid: 25
   #preferred locale is specific to ihris-manage based on the available locales
   locale: he_IL
   locale: en_US
   
   dn: uid=litlfred, app=ihris-qualify, ou=Application, dc=moh,dc=example,dc=gov
   role: admin
   appid: 25
   #preferred locale is specific to ihris-qualify based on the available locales
   locale: en_US
 
   dn: uid=litlfred, app=dhis2, ou=Application, dc=moh,dc=example,dc=gov
   role: guest
   appid: 42

Passwords

We will use SHA and salted SSHA. For a php implementation see this and this

openLDAP Server Configuration

This describes how to set up openLDAP for use with openMRS, DHIS and iHIS on an ubuntu machine. First, see this tutorial.

Here are the steps I followed:

sudo apt-get install slapd ldap-utils

• set the admin password to XXXXX. This should be set in the initialization string above

sudo dpkg-reconfigure slapd

• choose to Omit OpenLDAP server configuration?: Yes

In our scenario above initializing the UserAccess_LDAP module will add the entries for the People and Application organizational unit:

   dn: ou=People,dc=moh,dc=example,dc=org
   objectClass: organizationalUnit
   ou: People
  
   dn: ou=Application,dc=moh,dc=example,dc=org
   objectClass: organizationalUnit
   ou: Application