About
News
Downloads
Manual
Support
Examples
Releases
Community
Contact
Blog
Sources for file docs/access.txt in version 3.0
Click on a comment to hide it. Click here to show all comments.
AUTHENTICATON / ACCESS
The authentication/access modules of xnyo are designed to provide a simple and seemless way of
integration with many authentication sources.
Required Files
plugins/auth/*
plugins/class/access.php
plugins/class/input.php
Configuration Variables
Session Lifetime
This variable determines the idle timeout for a session. Its specified as a number of seconds.
Default:
(int) 86400
Examples:
// 86400 (24 hours) idle time is usually fine for standard websites
$xnyo->session_lifetime = 86400;
// 1800 (30 minutes) idle time is better for web based applications
$xnyo->session_lifetiem = 1800;
Authentication Module
This variable determines what authentication module should be called when using $auth->login();
The name here needs to correspond with an <a>authentication plugin</a>.
Default:
(string) sql
Examples:
// Use the SQL Database auth module
$xnyo->auth_type = 'sql';
Authentication Parameters
This is an array of values to pass to the authentication plugin. Exact contents depend upon the
authentication plugin. See the examples for more info.
Default:
(empty) array()
Examples:
// Use the SQL module for authenticating
$xnyo->auth_type = 'sql';
// And tell it we want to use the database specification plugin 'auth'
// this will tell it to look for dbspec/auth.php in your plugin dirs
$xnyo->auth_params = array
(
'table' => 'auth'
);
// Active Directory Authentication Parameters
$xnyo->auth_type = 'activedirectory';
// and the values
$xnyo->auth_params = array
(
// the LDAP/Active Directory Server
'server' => 'localhost',
// the Active Directory Domain to login to!
'domain' => 'mydomain.localhost.com',
// the Base DN
'basedn' => 'DC=mydomain,DC=localhost,DC=com'
);
Logout Redirect URL
When a user is logged out (due to session expiration/logout() call), xnyo will check to see if
this variable is set, and will issue a HTTP 302 Redirect to that location. The reason for logout can
be found in $_SESSION['_logout_reason'].
Default:
(null)
Examples:
// return them to the login page where an error message can be displayed asking for relogin
$xnyo->logout_redirect_url = '/index.php';
Load Session
This controls whether the session/access/language controls are loaded. If set to true, xnyo will
load them and check that the current session is still valid (hasnt expired, or been hijacked).
Default:
(bool) true
Examples:
// yep, go ahead and load the session stuff
$xnyo->load_session = true;
Methods
Session Check
bool $access->sess_check ()
This function is called automatically on startup if <a>load_session</a> is set to TRUE. It checks
the PHP session for a logged in user, checks that they havent been idle too long, that they havent
changed to a different subnet or changed browsers, either of which might suggest a hijacked session.
If any of these checks fail, the session will be closed and the user logged out.
Logout
bool $access->logout ([ string reason ])
This will close the session and log the user out, leaving <i>reason</i> in
<v>$_SESSION['_logout_reason']</v> if specified.
Example:
$access->logout('clicked logout');
ACL Check
bool $access->check (mixed acl)
This function will take an array of group/usernames/keywords/any combination thereof and check it
against the logged in users information. A comma delimited string is also accepted.
Keywords include 'required', which will return true if the user is logged in and 'none', which
will return true if the user is not logged in.
Example:
// see if the user is in the root group
if ($access->check('root'))
// do stuff
// is the user logged in?
if ($access->check('required'))
echo 'Logged in.';
else
echo 'Not logged in.';
// mixed group/username list
if ($access->check('root,admin,john'))
// do stuff if they're root, or an admin, or if their username is john
// passing array
$acl = array('root', 'admin', 'john');
if ($access->check($acl))
// same again
Subnet
mixed $access->subnet ([ string ip [, string subnet ]])
This function is used as part of session check, but can be used seperately also. IP will default
to $_SERVER['REMOTE_ADDR']
Get Username
string $access->user ()
This function will return the username of the currently logged in user, or false if none.
Set Language Control List
bool $access->set_lcl (string lcl)
Sets a language control list, this stops people from viewing the current page unless they using a
certain language, or langauges.
Set Access Control List
bool $access->set_acl (string acl)
Sets an access control list for paged base access control. You can pass it anything that
$access->check() will accept (array or string), and the function will halt page execution should the
client fail to meet the access requirements.
Login!
bool $auth->login (string username, string password)
This function will authenticate the supplied credentials against the current authentication module
and return true on success or false on failure.
If the login was successful, xnyo will spawn an authenticated session for this user and apply
their user details to $xnyo->user. If login failed,
the reason for the failure can be found in $auth->error with the following constants.
Authentication Failure Constants:
XNYO_AUTH_BLANK_USERNAME The username specified was an empty string ('')
XNYO_AUTH_BLANK_PASSWORD The password specified was an empty string ('')
XNYO_AUTH_NO_AUTH_TYPE The variable $xnyo->auth_type is empty and xnyo cannot load a
non-specified auth plugin.
XNYO_AUTH_NO_PLUGIN The variable $xnyo->auth_type either specifies an invalid plugin, or xnyo
was not able to locate the specified plugin inside the given plugin directories.
XNYO_AUTH_INVALID The username/password combination was incorrect. (They got one wrong, in other
words)
XNYO_AUTH_UNAUTHORISED xnyo was not able to load up a list of groups that this user belongs to,
so they have been denied access.
Examples:
// load up the auth plugin
$xnyo->load_plugin('auth');
// login!
if ($auth->login('username', 'password'))
echo 'Logged in successfully.';
else
echo 'Login failed.';
Plugins
SQL Database
Loaded via:
$xnyo->auth_type = 'sql';
The SQL Database plugin is designed to authenticate against a standard SQL database, almost any
SQL database.
It does this by running a search over a user table for a matching username/password combination,
and if none is found, the login is returned invalid.
The password is assumed to be stored as an md5() hash of the password text.
The basic required layout of this table is as follows:
create table auth (
username text,
password text,
groups text
);
This layout will allow xnyo to authenticate you with minimal or changes. If you wish to name your
table or fields
something else, like a part of a larger user table, we can simply specify a dbspec plugin for this
table.
Example:
// file: plugins/dbspec/auth.php
class dbspec_auth
{
var $_title = 'users';
var $_databse = 'my_database';
var $username = 'email';
var $password = 'password';
var $groups = 'something_strange';
}
This will cause xnyo to map its search for a user against the specified table, so in our example,
it would search
the table "users" inside "my_database" where the username was stored in the "email" field and the
password in the "password" field.
By default, xnyo will connect to whatever database you have setup in the <a>Database
configuration</a>.
xnyo will automagically search for a user specified "auth" dbspec plugin, but if you wish to call
it something else
you can simply specify the dbspec plugin name in the auth_params variable, and xnyo will search
for that instead.
Example:
// tell xnyo we want it to look for a dbspec plugin called "users"
$xnyo->auth_params['table'] = 'users';
If you use a client side md5 encoder to make a hash of the users password before it leaves their
web browser,
it is possible to have the SQL Auth Plugin forgo its md5 hashing of the password under the
assumption that it has
already been done. This is also useful if you simply dont want the password md5() hashed for
whatever reason.
Simply set the already_md5 key in $xnyo->auth_params and it will not md5() the password.
Example:
// tell xnyo *not* to md5() our password
$xnyo->auth_params['already_md5'] = true;
Active Directory
Loaded via:
$xnyo->auth_type = 'activedirectory';
The Active Directory plugin allows a standard PHP script to authenticate against a Windows 2000
Active Directory domain
through xnyo. It is important to note that this plugin requires PHP to be compiled with LDAP
support (for more information on LDAP and PHP,
see http://www.php.net/manual/en/ref.ldap.php).
This plugin is fairly limited in what it attempts to achieve, but it achieves them fairly well.
There is
not alot to this accept setting the required $xnyo->auth_params. These are listed below.
The Active Directory Auth plugin works as follows:
1. Connect to the Active Directory server through LDAP.
2. Attempt to bind to the server as the specified username/password.
3. Setup a search based on our username for all the groups that we belong to if we logged in
correctly.
4. Return these.
Parameters
Server
The IP Address/Hostname for our Active Directory Server.
Example:
$xnyo->auth_params['server'] = 'myserver.mydomain.com';
Domain
The Active Directory Domain that we are searching through. xnyo will first check to see if the
specified
username is in the form "username@domain" and will ignore this setting if it is.
Example:
$xnyo->auth_params['domain'] = 'my.active.directory.domain.com';
Base DN
The BaseDN that we need to search through to find our groups. This is in the LDAP basedn format,
and is usually, but not always simply converted from the domain.
Example:
$xnyo->auth_params['basedn'] = 'DC=my,DC=active,DC=directory,DC=domain,DC=com';
Advanced Usage Examples
Login.
This example assumes the following setup:
1. A user is presented a page with a simple username/password form.
2. xnyo variable filtering is turned on.
3. The default SQL authentication module is used, and the default table layout is used.
4. Smarty is not used for this simple example.
Example:
/**
* Filename: login.php
**/
/**
* Load xnyo, it is suggested that we load xnyo in either a prepend file, or an included file
* that is common for our whole site.
**/
require_once ('xnyo.class.php');
$xnyo = new xnyo;
/**
* Configuration: simple but more humanly readable error messages.
**/
$_errors = array
(
XNYO_AUTH_BLANK_USERNAME => 'You need to enter your username.',
XNYO_AUTH_BLANK_PASSWORD => 'You need to enter your password.',
XNYO_AUTH_NO_AUTH_TYPE => 'An internal server error has occured, please try again later or
email the admin at <email>',
XNYO_AUTH_NO_PLUGIN => 'An internal server error has occured, please try again later or email
the admin at <email>',
XNYO_AUTH_INVALID => 'Your username/password is invalid.',
XNYO_AUTH_UNAUTHORISED => 'You do not have the required access levels to login here.',
'other' => 'An unknown error has occured, please try again later or email the admin at <email>'
);
// First step, are they logging in now?
if ($_SERVER['REQUEST_METHOD'] == 'POST')
{
// Yes they are, filter through the username/password (usernames and passwords have special
input types)
$xnyo->filter_post_var('username', 'username');
$xnyo->filter_post_var('password', 'password');
// Load the authentication plugin
$xnyo->load_plugin('auth');
// log them in!
if ($auth->login($_POST['username'], $_POST['password']))
{
// Logged in successfully!
echo 'You logged in!';
exit();
} else
{
// Login failed. Make a nice error variable for us.
if (!empty($_errors[$auth->error]))
// known error
$error = $_errors[$auth->error];
else
// unknown error
$error = $_errors['other'];
}
}
/**
* Display the login form
**/
?>
<html>
<head>
<title>Example xnyo Login</title>
</head>
<body>
<?php // was an error message found? ?>
<?php if (!empty($error)): ?><font color="red">ERROR: <?=$error?></font><br /><?php endif; ?>
<form action="<?=$_SERVER['PHP_SELF']?>" method="POST">
Username: <input type="text" name="username" value="<?=$_POST['username']?>"><br />
Password: <input type="password" name="password" value=""><br />
<input type="submit" value="Login">
</form>
</body>
</html>
Site wide control.
Standard Access Control for page.
Code Block control.
Template level control.
Using SQL database.
Using Active Directory Database
Fail-over.
DEBUG CONSOLE INFORMATION
user config.
user information.
debug log.