mods/ldap/readme.txt

   1
   2 ATutor LDAP authentication module, version 0.2
   3
   4 This module provide basic functions of user authentication via LDAP Server, copy user information from LDAP Server and insert it into ATutor DB.
   5 Also module provide GUI for settings LDAP-auth and listing all user's which authenticated via LDAP.
   6 Transfering user passwords from browsers to ATutor server protected by strongly public key encryption (RSA with 512 bit key)
   7
   8         REQUIREMENTS
   9 1. PHP must be with ldap and openssl extensions (required for LDAP functions in ldap_lib.php and decryption in rsa.inc.php)
  10 2. In your server operating system must be installed OpenSSL package (OpenSSL package using when generated private/public keys)
  11
  12         INSTALLING
  13 Module consist of several php and java scripts and sql file for DB updating
  14 Next schema describe module structure and file in module
  15
  16         ----------------------------------
  17         admin/ ---------|
  18                         |- ldap_lib.php      -  Library of basic LDAP authentication functions. Provide connect to LDAP
  19                         |                       server, authentication users with
  20                         |                       password in LDAP server, coping user's info from LDAP to ATutor DB.
  21                         |- config_ldap.php   -  Script which generated page for configure LDAP authentication.
  22                         |- ldap_auth_log.php -  Script for genaratin page with list of user's which created via
  23                         |                       LDAP authoring
  24
  25         include/lib/ ---|
  26                         | - rsa.inc.php       - Library provide basic RSA decryption via private key and managament
  27                         |                       of authoring cookie which useed
  28                         |                       to check valid of encrypted string.
  29                         | - menu_pages.php    - Modified standart menu_pages.php file. In this file added strings
  30                         |                       which describe new pages for ATutor administrator.
  31                         | - pk.pem            - Example private key
  32
  33         rsa/  ----------|
  34                         | - base64.js
  35                         | - jsbn.js
  36                         | - prng4.js
  37                         | - rng.js
  38                         | - rsa.js             - ALL of this files using for encryption user password in login page.
  39                         |                        Using jscript's from http://www-cs-students.stanford.edu/~tjw/jsbn/
  40
  41         themes/default/-|
  42                         | - login.tmpl.php     - Modified standart login.tmpl.php. Added new hidden input and
  43                         |                       password encryption via RSA public key.
  44
  45         jscript/jqgrid -|   -                  javascript files required for AJAX table in admin LDAP log page
  46                         |
  47         login.php   -----------------------------Modified standart login.php. To this file added required functions
  48                                                  for RSA encryption/decryption and LDAP communication.
  49
  50 Also module has:
  51 1. atutor.ldap.struct.sql file - Use this file to update your ATutor DB and create requried tables.
  52
  53
  54
  55 Install module:
  56
  57 1. Copy all files from atutor.ldap.mod  to your ATutor and put them in appropriate directories (see module schema).
  58
  59 2. Use atutor.ldap.struct.sql to modify your ATutor DB. In this step you may use next command:
  60         mysql -u "user_name" -p "your_atutor_DB" < atutor.ldap.struct.sql, then press ENTER and put "user_password"
  61                 where "user_name"      - user that can modify your ATutor DB (see your ATutor's
  62                                          include/config.inc.php)
  63                       "user_password"  - password for access "user_name" to your ATutor DB (see your ATutor's
  64                                          include/config.inc.php)
  65                       "your_atutor_DB" - name of DB which used by your ATutor
  66
  67                 EXAMPLE:  mysql -u atutor -p atutor154 < atutor.ldap.struct.sql
  68
  69 3. Now you must generate a private key using openssl.(This module has example private key, but strongly recomended     generate new private key)
  70
  71   To generate RSA private key use next commands:
  72
  73         $ openssl genrsa -out priv_key.pem.
  74         Generating RSA private key, 512 bit long modulus
  75 .       .++++++++++++
  76         ..............++++++++++++
  77         e is 65537 (0x10001)
  78         $
  79
  80         Private key will be saved in priv_key.pem
  81
  82 4. Copy your private key in a place which can't be readed by everyone (don't copy your private key to directory,       which can be readed by Apache  web-server), but rsa.inc.php must has access to private key.
  83    In my ATutor installations I do following steps (let private key stored in priv_key.pem):
  84                 1. Copy priv_key.pem to my_atutor_installation_path/include/lib/ directory.
  85                 2. Use chmod 644 priv_key.pem (now rsa.inc.php has read access to priv_key.pem !!!)
  86                 3. In httpd.conf of my Apache web server I put next dirictives
  87                                 <Directory "my_atutor_installation_path/include/lib/">
  88                                         Order deny,allow
  89                                         Deny from all
  90                                 </Directory>
  91                         Now, include/lib/ directory protected and nobody can read priv_key.pem
  92
  93    Path to your private key must be defined in rsa.inc.php
  94
  95 5. Getting modulus from private key and configure rsa.inc.php
  96
  97         $ openssl rsa -in priv_key.pem -noout -modulus
  98         Modulus=DA3BB4C40E3C7E76F7DBDD8BF3DF0714CA39D3A0F7F9D7C2E4FEDF8C7B28C2875F7EB98950B22AE82D539C1ABC1AB550BA
  99         $
 100
 101         Copy modulus to rsa.inc.php
 102
 103 6. Confgiure LDAP authentication
 104         1. Login in your ATutor system.
 105         2. Go to System Prefernces and then to LDAP Authentication page
 106         3. Set LDAP Server name. It may in two variants, first - FQDN, second - LDAP URL ("ldap://your_ldap_server"
 107            or "ldap://xxx.xxx.xxx.xxx", where xxx.xxx.xxx.xxx - IP address of LDAP server
 108         4. Set LDAP port. By default using standart LDAP port
 109         5. Set LDAP Server tree. You must define LDAP tree (or subtree) where stored user's entries.
 110                 EXAMPLE. If LDAP server has name  example.com and it has subtree with name "accounts". Subtree
 111                 "accounts" has children subtree "users" where stored user's entries. So, your LDAP Server tree
 112                 will be "ou=users,ou=accounts,dc=example,dc=com".
 113
 114                 Contact with your LDAP server administrator to get full information about LDAP structure.
 115         6. Set attributes of user entries.
 116                 In "LDAP Server field" you must set name of LDAP entries attribute.
 117                 EXAMPLE. If user entries in LDAP has 6 attributes, 1 is uid attribute, where stored user's login,
 118                 2 is password attribute, where stored user's password, 3, 4, 5 is l_name, f_name, s_name attributes where stored user's last, first and second names, and 6 attribute is mail, where stored user's email.
 119                 In this case, you must set in "Login" field - "uid", "E-mail" field - "mail", in "Last name", "First name", "Second name" fields - "l_name", "f_name", "s_name".
 120
 121                 Contact with your LDAP server administrator to get full information about entries attributes.
 122
 123
 124 This module tested (and it's work) in next platforms
 125
 126         1. OpenSUSE 10.2 + Apache 2.2.3 + MySQL 5.0.26 + PHP 5.2.0 + OpenLDAP 2.2
 127         2. Slackware 11.0 + Apache 1.3.37 + MySQL 5.0.33 + PHP 4.4.6 + OpenLDAP 2.3.32
 128         3. Fedora 10 + Apache 2 + MySQL 5.0.23 + PHP 5.2 + OpenLDAP
 129
 130 Currently ATutor + ldap module running on Fedora 10 + Apache 2.2.3 + MySQL 5.0.22 + PHP 5.1.6  and LDAP server running on Fedora Core 4 + OpenLDAP 2.2.4 In  this configuration system running aproximetly 25 month.
 131
 132 This module with a few changes can be used for user authentication via Microsoft Active Directory.
 133
 134 This module distributed "as is" and can be modified for your needs.
 135
 136 If you use or modified this module, please, email me.
 137
 138          smal (Serhiy Voyt)
 139          smalgroup@gmail.com
 140
 141          Distributed under GPL (c)Sehiy Voyt 2005-2009
 142