File: twzAuth.doc.txt

Recommend this page to a friend!
  Classes of Tony  >  twzAuth  >  twzAuth.doc.txt  >  Download  
File: twzAuth.doc.txt
Role: Documentation
Content type: text/plain
Description: Documentation
Class: twzAuth
Authenticate users using HTTP Basic authentication
Author: By
Last change: tweak
Date: 5 years ago
Size: 9,865 bytes
 

Contents

Class file image Download
twzAuth.doc.txt


twzAuth.class                                      v0.1.1 2015-03-22
-----------------------------------------------------------------------------



I N T R O D U C T I O N
==========================================

twzAuth is an ultra-simple user "login" script using basic 
HTTP authentication, and allowing easy user management.

Similar functionality is provided by Apache using .htaccess/.htpasswds, 
and available via cPanel as "Password protect directories".

While twzAuth is similar to the Apache HTTP auth, IT IS NOT THE SAME.
In particular, Apache HTTP auth protects every file in a directory, 
while twzAuth only protects specific php pages that include the 
$auth->validate() call.

twzAuth is intended as a quick solution for a small number of users. 
If you have more than 10 or 20 users, you probably should consider a 
more robust database solution.


I N S T A L L A T I O N
==========================================
Before uploading to your server, make sure to edit the include file/s 
with your preferred settings. The requirements are slightly different 
for simple mode vs extended mode (modes are explained below).

For simple mode: change the $ValidUsers array to set the usernames and 
passwords you want to use.

For extended mode: change the datastore pathname (default './users.db') 
to your preferred location, and change the setAdmin() to your preferred 
admin username and password.


R U N T I M E   M O D E S
==========================================

twzAuth runs in one of two modes:

    SIMPLE MODE:
        The class is instantiated with a plain text array of Usernames and 
        passwords. Users and passwords can be changed by editing the php 
        script. The only public method applicable in simple mode is validate().
        All users are equal in simple mode; there is no concept of 'admin user'.
    
    EXTENDED MODE:
        The class is instantiated with a datastore pathname (string). Usernames 
        and passwords are stored in that file. Some users may be Admin users 
        who can add, edit, and delete users, and change passwords via a protected 
        web page. Additional custom fields are also supported (eg First name, 
        Last name).
        
SIMPLE MODE:
------------------------------------------
For example, protecting a single php page with twzAuth in 'simple mode' is as 
easy as adding these lines at the top of the file:

    require 'twzAuth.class.php';
    $auth=new twzAuth( array('admini'=>'stR8_Er$') );
    $Username = $auth->validate();

As you can see, the username and password is hard-coded in the script, so you 
can easily change the password or add more users by editing the script and 
re-uploading it. The variable $Username will contain the username that has 
been authenticated (in this case it will always be 'admini' because that's 
the only valid user). To protect multiple php pages, move these lines into 
a separate include script, and include it in each page.

EXTENDED MODE:
------------------------------------------
Extended mode offers more features and possibilities, and is just as easy to implement:

    require 'twzAuth.class.php';
    $auth=new twzAuth( '../../users.db' ); // TIP: datastore is safer above the web root
    $auth->setAdmin('tony', 'e#tAg683%eWs.-(');
    $Username = $auth->validate();

In this case you specify a file where user information will be stored, and by 
calling setAdmin() with a username and password, you ensure there is an initial 
user so you can log in. You can add, update or delete users from a special 
web page designed for this (see included example admin.php). You can change your 
own password this way too; setAdmin() won't do anything if the user alreay exists.


P U B L I C   M E T H O D S
==========================================

As mentioned above, 'simple mode' only supports one method: validate().
There are additional methods available in extended mode, some of which can 
only be called by an admin user.



__construct($Users, $Realm=false, $FailHtml=false, $CustomFields=false)
_____________________________________________________________________________
    The twzAuth class is instantiated with at least one parameter ($Users); 
    the other parameters are optional, and if missing or 'false', will be 
    set to default values.

    $Users
        1. For simple mode, an array of passwords indexed by Username.
        eg array( 'stacie'=>'Wd$5gHf^4', 'danny'=>'5r4RF$4eD%', 'threesocks'=>'R323&*(j4fd' )
        2. For extended mode, a string specifying the pathname of the datastore.
        eg '../../myUsers.db'
        The specified directory must exist (preferably above the web root), and 
        the file must be writable by PHP.
    
    $Realm
        A string presented to the user, akin to a name for the protected page/s.
        If missing or false, defaults to 'Restricted area'.

    $FailHtml
        A string containing HTML that will be sent to the browser if user 
        authentication fails (ie if the user cancels the dialog box).
        If missing or false, defaults to '<h2>401 Unauthorized</h2>'.

    $CustomFields
        (extended mode only) a string of comma-separated custom field names. 
        For example if you want to record each user's name and date of birth, 
        this parameter could be the string 'First name, Last name, dob'.
        
        If missing or false, no custom fields will be used.
        
        If you use custom fields the addUser(), editUser() and getUserInfo() 
        methods will accept or return the custom field values, but it's up to 
        you to manage how they are used or interpreted.

        If you have a custom field which is entered via a textarea input 
        (eg 'Comment'), then it may contain newline or tab characters. 
        These will be encoded for storage purposes, and you will need to 
        decode them for display. For example:
        echo str_replace(array('\r', '\n', '\t'), array("\r", "\n", "\t"), $User['Comment']);



validate($AdminOnly=false)
_____________________________________________________________________________
    This is the principal method of the twzAuth class. It attempts to validate 
    the user against the current list of usernames and passwords. Username may 
    be entered by the user with any mix of upper/lower case.
    
    On success, it returns the validated username (with upper/lower case as entered 
    by the user). On error, the method doesn't return at all; instead it sends 
    '401 Unauthorized' headers to the browser, and displays the HTML specified in 
    $FailHtml (__construct parameter).
    
    If the $AdminOnly parameter is set to true, success will only occur if the 
    validated user is an admin user (extended mode only). An alternative to this 
    is to call validate() without the parameter, then check isAdmin() and take 
    appropriate action.


addUser($Username, $Fields)
_____________________________________________________________________________
    Adds a new user to the system. This method can only be run by an admin user.

    $Username
        Username of the new user
    
    $Fields
        If you just want to set the user's password, this parameter can be a string.
        To set any custom fields, it will be an array of field names and values.
        eg array( 'First name'=>'Kris', 'Password'=>'xXx345+eWq' )
        If a password is specified as an empty string, a random password will be 
        generated, which can be discovered by calling newPassword() immediately 
        following this method.


deleteUser($Username)
_____________________________________________________________________________
    Deletes the user with the specified Username. This method can only be run 
    by an admin user.


editUser($Username, $Fields)
_____________________________________________________________________________
    Updates information for an existing user. This method can only be run 
    by an admin user.
    
    $Username
        Username of the user to update
    
    $Fields
        Password string, or array of field names and values - refer to the
        addUser() method for a full explanation.


getUserInfo($Username=false)
_____________________________________________________________________________
    Returns an array of information for the specified user, or the current 
    user if $Username not specified. Only an admin user can specify $Username.


getUsernames()
_____________________________________________________________________________
    Returns a simple array of all usernames. This method can only be run 
    by an admin user.


getUsers()
_____________________________________________________________________________
    Returns an array containing all information held for all users.
    This method can only be run by an admin user.


isAdmin()
_____________________________________________________________________________
    Returns true if the current user is an admin user, false if not.


lastError()
_____________________________________________________________________________
    Returns a string containing the last error, or false if none.


newPassword()
_____________________________________________________________________________
    Returns the last password saved by addUser() or editUser(), 
    or false if none.


setAdmin($Username, $Password)
_____________________________________________________________________________
    If user $Username doesn't exist, this method adds it as an admin user.
    This is mainly for adding the initial user in extended mode.



For more information send a message to info at phpclasses dot org.