README

This directory contains authentication modules.

Each of these modules describes a different way to 
check that a user has provided a correct 

   - username, and 
   - password.

Even when external forms of authentication are being
used, Moodle still maintains the internal "user" table 
with all the associated information about that user such
as name, email address and so on.

The active method is set by the admin on the Configuration page.


email - authentication by email  (DEFAULT METHOD)

    - user fills out form with email address
    - email sent to user with link 
    - user clicks on link in email to confirm
    - user account is created
    - user can log in


none  - no authentication at all .. very insecure!!
    
    - user logs in using ANY username and password
    - if the username doesn't already exist then
      a new account is created
    - when user tries to access a course they 
      are forced to set up their account details

manual - internal authentication only

    - user logs in using username and password
    - no way for user to make their own account


ldap  - Uses an external LDAP server

    - user logs in using username and password
    - these are checked against an LDAP server
    - if correct, user is logged in
    - optionally, info is copied from the LDAP
      database to the Moodle user database

    (see the ldap/README for more details on config etc...)


imap  - Uses an external IMAP server

    - user logs in using username and password
    - these are checked against an IMAP server
    - if correct, user is logged in
    - if the username doesn't already exist then
      a new account is created


pop3  - Uses an external POP3 server

    - user logs in using username and password
    - these are checked against a POP3 server
    - if correct, user is logged in
    - if the username doesn't already exist then
      a new account is created


nntp  - Uses an external NNTP server

    - user logs in using username and password
    - these are checked against an NNTP server
    - if correct, user is logged in
    - if the username doesn't already exist then
      a new account is created


db  - Uses an external database to check username/password
    
    - user logs in using username and password
    - these are checked against an external database
    - if correct, user is logged in
    - if the username doesn't already exist then
      a new Moodle account is created


------------------------------------------------------------------------------------

Authentication API

This file describes Moodle interface functions to authentication modules.

Most of functions are from ldap-authentication module and are not implemented (yet?)
on other modules. Please feel free to extend other modules to support same features
or roll your own module.

Some of new function are still tested and are not documented here yet.



AUTHENTICATION
Basic fuctions to authenticate users with external db

Mandatory: 
    
    auth_user_login ($username, $password) 
    
    Authenticate username, password with userdatabase.

    Returns:
    true if the username and password work
    and false if they don't

Optional:
    
    auth_get_userinfo($username)
    
    Query other userinformation from database.

    Returns:
    Userinformation in array ( name => value, .... 
    or false in case of error

    auth_validate_form(&$form, &$err)
    
    Validate form data.

    Returns:
    Bool. Manipulates $form and $err arrays in place


COURSE CREATING

    auth_iscreator($username)

    should user have rights to create courses

    Returns:
    True if user have rights to crete cources otherwise false


USER CREATION

Functions that enable usercreation, activation and deactivation
from moodle to external database
  
  
    auth_user_exists ($username) 
   
    Checks if given username exist on external db

    Returns:
    true if given usernname exist or false
 
    auth_user_create ($userobject,$plainpass) 
 
    Creates new user to external db. User should be created
    in inactive stage until confirmed by email.

    Returns:
    True on success otherwise false


    auth_user_activate ($username) 
    
    activate new user after email-address is confirmed

    Returns:
    True on success otherwise false


    auth_user_disable ($username) {
    
    deactivate  user in external db.
    
    Returns:
    True on success otherwise false



USER INFORMATION AND SYNCRONIZATION

    auth_get_userlist () 

    Get list of usernames in external db.

    Returns:
    All usernames in array or false on error.
    

    auth_get_users($filter='*') 
    
    Get ALL USEROBJECTS FROM EXTERNAL DB.

    Returns:
    Array of all users as objects from external db