pajamas
modular authentication system
intro..
pajamas is an acronym for "php and javascript advanced md5 authentication system", and while there is a "plain" module available these days, pajamas was primarily designed to load authentication modules that utilize both server-side and client-side code, but it can handle either.For more information about pajamas, examples, updates, etc., see here..
pajamas.php is the main pajamas program. This script gets the users authentication status from whatever module is currently loaded, probably 'pj'. Basically it's a container interface, enabling us to load plug-in authentication modules on-the-fly. They live in a folder called, unsurprisingly, "modules".New modules can be plugged into pajamas with trivial ease (drop them in the folder and call them), and it is hoped that more modules will become available over time, as encryption and authentication schemes evolve. If you want to write a pajamas authentication plug-in, check out the two included modules, and the notes within
pajamas.php.With a single pajamas installation, you can run multiple authentication systems simultaneously, all over your site, even in the same folder, each with a completely different set of characteristics, yet all running from one central engine.
usage:
pajamas has two modes of operation, "simple", and "advanced". like this..simple..
To use pajamas in "simple" mode, do this..
include 'pajamas.php';
$auth = new pajamasSimple();
That's it!
The simple module will setup the current authentication system for you and spit out either a login form or logout button, depending on the user's current authentication status. Quick and handy.
If you need to check their authentication at any time on your page, query the value of $auth->auth_user(), like this..
if ($auth->auth_user()) { /* do admin stuff */ } else { /* do public stuff */ }
notes:
- In the real world, your include statement would probably look something
different, perhaps like this..
include $_SERVER['document_root'].'/inc/pajamas.php';
- You can use a unique id when you start the pajamas interface, like this..
$auth = new pajamasSimple('uid');
'uid' can be whatever you like, or omitted, in which case it defaults to 'pajamas'. The uid gets tagged onto session array's name. If you use the pajamas engine to run lots of different login situations at once, give each of them a different uid, and they won't overlap.
Or you may prefer to have them all share the same uid. That way, completely separate web applications running on your site can all share a site-wide login. Very handy.
- When you run in "simple" mode, because you cannot override the module's built-in preferences, you will need to ensure that they are correct for your installation, and if need be, alter them inside the *module* itself; for instance, the correct location of your JavaScript md5.js file, e.g..
var $_code_location = 'inc/js/md5.js';
- Although, in "simple" mode, there's no way to specify preferences by regular methods, you can specify which module to use by passing it in your uid, like this..
include 'pajamas.php';
$auth = new pajamasSimple('Myuid-plain');
"Myuid" being your chosen id string (whateveryoulike), and "plain" being the name of the pajamas module you wish to use. This way you could also duplicate favourite modules, altering the settings, rename to "whatever", and then call $auth = new pajamasSimple('Myuid-whatever'); I may extend this capability to include other simple interface preferences. Let me know what you think.
foibles
- You must ensure your session handling is correctly configured for simple mode to work as expected. When I uploaded the simple demo to my host (which runs phpsuexec) it refused to allow me to login. I added a local php.ini (or
.user.inias it is sometimes); whose only session directive wassession.use_trans_sid = 0- though my root php.ini has the session path set correctly - this only needs to be specified once in the site's root php.ini, afaik; It solved the problem immediately.
I've seen similar behaviour with WAMP/php5 on XP/SP2, so perhaps an investigation is in order. Note: This in no way affects pajamas regular usage, only the "simple" interface, so if it affects your server, don't use the simple interface (which is just for n00bs, anyway), use the regular (aka "advanced") interface, here explained..
advanced..
If you need more control, you can unleash pajamas' full capabilities like this..
include '/path/to/pajamas.php';
$auth = new authModule('uid');
If you need to override any pajamas default preferences, do it like this..
$auth->_createForms = false;
$auth->_default_module = 'pj';
$auth->_code_location = 'js/md5.js';
At the point you call the $auth->auth_user() function, pajamas will check the users' credentials with the chosen authentication module (currently either 'pj', 'sha1', or 'plain'). If they are authorised, pajamas will return true, if not, it returns false..
if (!$auth->auth_user()) {
echo $auth->getAuthCode(); // echo the pj javascript include
echo $auth->getLoginForm(); // echo a login form
}
if ($auth->auth_user()) {
echo $auth->getLogoutButton(); // maybe a logout button.
}
notes:
- You can do $auth->getLoginForm(true) to get a more simple version of the input with no divs around it; same for $auth->getLogoutButton();, handy sometimes. Coupled with the $auth->_createForms = true/false, you can pretty much do whatever you like, style-wise.
- All pajamas modules can be used in simple or advanced mode.
- See also "Simple" notes (above) and the properties (below).
To run the default module ('pj'), you'll need the md5.js JavaScript file available somewhere on your site (included), and it must be loaded in your page (either automatically in "simple" mode or by using echo $auth->getAuthCode(); in advanced mode).
If you need help, mail me @ corz.org or if you think a solution to your issue would be valuable to others, drop a comment on the pajamas page..
https://corz.org/server/security/pajamas.php
Have fun!
;o)
© 2004-> corz.org ;o)
ps.. big thanks to PCheese for all the help with the pj OOP stylings.
d00D! I get it now! And I hope you like where I took it!
properties..
you set these externally, like so..
$auth->_login_password = 'MyPassword';
default module
(string) name of module file (minus .php extension)current choices are 'plain' or 'pj' (the best)
If, for some insane reason, you don't have access to a JavaScript- capable browser, use 'plain', otherwise, use 'pj'.
the plain module can be configured in exactly the same way as the pajamas module, and has many of its features, too; sessions, IP check, time-out, etc., the only difference being that the password is sent over the wire in plain text.
Though unlike HTTP basic authentication, which send the password with every single request, with the plain module, the password travels over the wires one time only.
var $_default_module = 'pj';
password
(string) default: 'password';a quick and dirty way to store your password..
or you could keep it in a database, or include from another file,. include '/some/other/place/config.php'; and set it externally..
$auth->_login_password = 'MyPassword';
Passwords are case-sensitive.
var $_login_password = 'password';
IP address check?
boolean (true/false) default: true;normally, we check the IP address of the authorising browser. However, if the user is behind a proxy farm (very unusual), this will break his session, as his IP will change with (possibly) each request. If you have users behind proxy farms, (or you are) set this to false, or else advise them to use *yet another* proxy (two proxies).
var $_check_ip = true;
do time-out?
boolean default: true;we can specify a time-out for the session. if you set this to false, the session is live until the client's browser is quit, or they log out.
var $_do_time_out = true;
time-out
(integer, minutes) default: 60;an hour is reasonable, anything goes. the demo uses 0.5 (30 seconds)!
var $_session_time = 60;
big luser
(integer) (max failed attempts) default: 10;they tried and tried, but it just isn't happening. Or else they are taking the p*ss. A script perhaps, some brute force. Whatever, it would probably be best for everyone if we halted them in their tracks after how many failed login attempts?
var $_big_luser = 10;
kick bad users?
boolean (true/false) default: false;optionally we can prevent even correct logins from browsers that repeatedly sent bad logins..
If you set this to true, after($_big_luser) failed login attempts, the property $auth->_bad_user) will be set to true. Now, even a correct login will fail to authenticate.
You can check for bad users, and then do what you like with them..
if ($auth->_bad_user) { die('go away!');
If you leave kick_bad_users set to false, a correct login will override all previous bad logins.
The idea is, someone may be attempting to login from your terminal, and fail, so they receive a message informing them of the futility of it, *hopefully* they will stop now. If the *real* admin comes along, he should be able to log straight in, and shouldn't have the inconvenience of restarting the browser just because some twat was fooling around. But you can disable this behaviour by simply setting this to true.
var $_kick_bad_users = false;
show error messages?
boolean (true/false) default: true;pj generates some messages for the various error conditions, you can use these however
you like, and latest message is always in "_auth_message"
If you like, you can have pj display these messages just above the login form, so the user is aware that their password was incorrect, or whatever..
var $_do_messages = true;
create containing forms?
boolean (true/false) default: true;If you are already inside a form, set this to false to avoid nesting forms, which will break html valiadation, among other things (including the md5)..
$auth->_createForms = false;
Remember you can also pass "true" to your form input function, to have a simple, div-less output, like this..
$auth->getLoginForm(true);
var $_createForms = true;
autocomplete="off"
boolean (true/false) default: false; (validates, but is annoying)a good, mostly supported proprietary Internet Explorer property.
With this set to true, browsers will not annoy you to try and save the password (which, at least with the 'pj' module, is a one-shot useless mish-mash that will be useless the instant you logout, anyway).
Set this to true to add 'autocomplete="off"' to your password field. TADA! One of the rare occasions where Internet Explorer leads the way!
var $_no_autocomplete = false;
code loaction.
(string) default: '';Some modules may require included code.
In "pj", this sets the default location of javascript MD5 functions file and will be used to create the <script> tag that includes the JavaScript MD5 functions on your page, like this..
echo $auth->getAuthCode();
You can override the location by setting this..
$auth->_code_location = 'inc/md5.js';
*before* you echo the code. relative or absolute paths are fine, just like a regular javascript include.
var $_code_location = '';
methods..
pajamas presents the following methods to your application..
(you can call these from your application)
auth_user()
the main function, returns a boolean, true on authenticated, false if not.
getAuthCode()
returns an html string to load any external scripts (eg 'md5.js' <script> tag)getLoginForm([true])
returns the module's login form (pass true for a simple• version)getLogoutButton([true])
returns the module's logout mechanism, usually a button. (ditto•)getSelf()
like PHP_SELF, the path of the calling script.getBadUser()
boolean flag denoting browsers that sent too many bad logins.remainingTime()
if using time-out, this returns the number of seconds remaining.getErrors()
spit out a string of any errors that may have occured. pajamas will catch session errors of type E_NOTICE, and store them, so you can use this to spit them out, if you really must.- simple versions of form inputs come raw without divs, so you can lay them into your style very freely (also see the $_createForms; property).
devlopers: If you are writing a pajamas module, it must handle all these methods. If your module doesn't support a particular method, simply return false.