MRBS Users Authentication
=========================
Principles
==========
User interface
--------------
MRBS pages can be accessed and used, depending on the user's access level.
There are three levels of access in MRBS:
- Level 0 - Unknown user
- Level 1 - Authenticated user
- Level 2 - Administrator
Level 0 users can view most pages, but cannot make any change.
Level 1 users can make bookings, and can change their own bookings.
Level 2 users - The administrators - are allowed to modify other people's
bookings. Administrators also have the ability to add and remove rooms and
areas.
Before accessing a restricted page, MRBS prompts the user for a name and
password. Then it connects to an authentication server, which is responsible
for deciding if the user/password pair is valid. If it is, MRBS then checks if
the name is in its list of administrators. Finally MRBS grants access to the
page at the right level. The name and password are recorded for the duration of
the session, and won't be asked for again.
Configuration
-------------
MRBS authentication configuration is done in file config.inc.php.
This file contains a section for authentication parameters, where several
choices must be made:
- The session management scheme. (How to prompt for a user/password,
and how keep track of it)
- The authentication method. (What kind of server will verify the
user/password validity)
- The list of administrators (not used by the 'db' authentication method)
There are several alternative authentication methods. They differ by the type
of authentication server they can connect to, and by the kind of program used
for communicating with that server. Each method is implemented in a pluggable
module. There are two general categories:
- Internal PHP modules, which connect directly to an authentication
server. These modules may require additional parameter settings in
config.inc.php.
- External programs, that do the same after being invoked by the
special "ext" PHP authentication module.
Internal PHP modules support the following kinds of authentication servers:
LDAP servers; POP3 email servers; IMAP email servers; NW servers.
In addition, three special internal modules support a local list of users for
one; a local list of users stored in the database for the second; and
authenticating anybody for the other.
External programs support: NT Domain controllers; Netware servers; PAM servers.
Which authentication scheme to choose
=====================================
The default authentication scheme is 'db', which stores users' details in the
MRBS database in the 'users' table. However, the right choice for you will
depend on whether your users are already listed somehere else.
If they're all in a closed organization (eg a private company or a university),
then this organization probably already has its own authentication service.
MRBS can connect to several kinds of services, such as LDAP servers, NT domain
controllers, Netware servers and POP3 or IMAP mail servers.
If your website is using a Joomla! or WordPress CMS and you already require your
users to authenticate, then MRBS can be configured to authenticate your users
against the existing list of users in the CMS.
PHP authentication modules
--------------------------
+---------+------------------------+-------------------+------------------------+
|Type |Description |Pros |Cons |
+---------+------------------------+-------------------+------------------------+
|none |Every user is accepted. | | |
| |This was for example the| | |
| |case of the MRBS 1.1 IP | - Very simple to | - No security at all. |
| |address and computer | setup. | |
| |name "authentications". | | |
+---------+------------------------+-------------------+------------------------+
|config |Users are listed in | | |
| |config.inc.php. | | |
| | | - Simple to | - Users cannot update |
| | | setup. | their own password. |
| | | | |
| | | - Not dependent | - Administrators |
| | | on an external | manually set the user |
| | | authentication | passwords, which is |
| | | server, so usable| against normal |
| | | on the Internet. | confidentiality rules.|
| | | | |
+---------+------------------------+-------------------+------------------------+
|db |Users validated using | | |
|(default)|web-based authentication| - Simple to setup| |
| |based on a table in mrbs| | - Does not use |
| |database | - Built in MRBS | existing directory |
| | | but more secure | |
| | | than 'config' | |
| | | | |
| | | - Easy to | |
| | | configure | |
+---------+------------------------+-------------------+------------------------+
|db_ext |Users validated using | | |
| |a table in an external | - Uses an | |
| |database | existing | |
| | | authentication | |
| | | database thereby | |
| | | saving directory | |
| | | duplication. | |
| | | | |
| | | - easy to | |
| | | configure | |
| | | | |
+---------+------------------------+-------------------+------------------------+
|ldap |Users validated using | | |
| |LDAP directory services.| | |
| | | - For corporate | - Does not work on the|
| | | intranets using | Internet? |
| | | LDAP directory | |
| | | services. | |
| | | | |
+---------+------------------------+-------------------+------------------------+
|pop3 |Users validated by a | | |
| |POP3 mail server. | | |
| | | - For groups of | - Technically works on|
| | | users all having | the Internet, but it's|
| | | an Email address | unlikely all users of |
| | | on the same | a site will have an |
| | | server. | Email address on the |
| | | | same mail server. |
| | | | |
+---------+------------------------+-------------------+------------------------+
|imap |Users validated by an | | |
| |IMAP mail server. | | |
| | | - For groups of | - Technically works on|
| | | users all having | the Internet, but it's|
| | | an Email address | unlikely all users of |
| | | on the same | a site will have an |
| | | server. | Email address on the |
| | | | same mail server. |
| | | | |
+---------+------------------------+-------------------+------------------------+
|imap_php |A more up to date | | |
| |version of imap | | |
+---------+------------------------+-------------------+------------------------+
|nw |Users validated by | | - This is only going |
| |Netware server | | to work on Linux. |
| |(user contrib.) | - ? | |
| | | | |
+---------+------------------------+-------------------+------------------------+
|ext |Validation is delegated | | |
| |to an external program. | | |
| | | - Lots of | - Most available |
| | | possibilities. | programs work only |
| | | | under Unix. |
| | | | |
+---------+------------------------+-------------------+------------------------+
|joomla |Users are validated | | |
| |against a Joomla! | | |
| |installation running on | | |
| |the same server | | |
| | | | |
+---------+------------------------+-------------------+------------------------+
|wix |Users are validated | - Users don't | - Not a single signon/|
| |against members | need to have | signoff solution |
| |registered on a Wix | two sets of | - Can be slight delays|
| |website. | login details | in retrieving user |
| | | - Administrators | details from a |
| | | only have to | remote Wix site |
| | | manage users in| |
| | | one place (Wix)| |
| | | | |
+---------+------------------------+-------------------+------------------------+
|wordpress|Users are validated | | |
| |against a WordPress | | |
| |installation running on | | |
| |the same server | | |
| | | | |
+---------+------------------------+-------------------+------------------------+
|cas |Users are validated | - Federated login| - Requires a CAS |
| |against a CAS server | - Single signon | server |
| | | - Single signoff | |
+---------+------------------------+-------------------+------------------------+
|saml |Users are validated | - Federated login| - Must set up |
| |against a SimpleSamlPhp | - Single signon | SimpleSamlPhp |
| |installation running on | - Single signoff | - SAML knowledge |
| |the same server | - Hooks into | recommended |
| | | SAML infra | |
+---------+------------------------+-------------------+------------------------+
|idcheck |For use with mod_idcheck| | |
| |idcheck.sourceforge.net | | |
| |Must be used together | | |
| |with the 'remote_user' | | |
| |session scheme. | | |
+---------+------------------------+-------------------+------------------------+
External authentication programs
--------------------------------
+------------------+------------------+-----------------+-------------------+
|Program |Description |Pros |Cons |
+------------------+------------------+-----------------+-------------------+
|crypt_passwd.pl |Perl script which | - Easy to setup | - Relies upon a |
| |reads a 'shadow' | | special users |
| |style file with | | file. |
| |usernames and | | |
| |crypted passwords.| | |
+------------------+------------------+-----------------+-------------------+
|auth_pam.pl |Uses PAM | | |
| | | | |
| | | - For Unix | |
| | | system uses PAM| |
| | | (especially | |
| | | Linux, but also| |
| | | SUN Solaris) | |
| | | | |
+------------------+------------------+-----------------+-------------------+
Which session scheme to choose
==============================
The session scheme is the way the user and password is queried and recorded.
The default session scheme is 'php'. Some authentication schemes, eg 'joomla',
'wordpress', 'cas' and 'saml' require you to use their own session schemes. The
others are left in for historical reasons:
+---------+------------------------------+--------------------+----------------+
|Type |Description |Pros |Cons |
+---------+------------------------------+--------------------+----------------+
|php |Use PHP's native session | | |
|(default)|handling. Recommended. | | |
| |Session data is saved in the | - Recommended by | - Any? |
| |MRBS database. | PHP doctors, PHP | |
| | | moms, etc. | |
| | | | |
+---------+------------------------------+--------------------+----------------+
|http |Use the "HTTP basic | | |
| |authentication" protocol to | | |
| |get a user/password popup. | - Simple. | - Incompatible|
| | | | with IIS web |
| | | - This was the | servers. |
| | | default in MRBS | |
| | | 1.1 for most | - No way to |
| | | authentication | log out. |
| | | schemes. | |
| | | | |
+---------+------------------------------+--------------------+----------------+
|cookie |Save the user/password in | | |
| |cookies on the client's web | | |
| |browser. | - Less demanding | - Some users |
| | | for the server | disable |
| | | than PHP native | cookies on |
| | | sessions. (No | their browser.|
| | | files stored) | |
| | | | |
+---------+------------------------------+--------------------+----------------+
|nt |The users identity is queried | | |
| |AND validated by an NT/IIS | | |
| |server running in | - For corporate | - Incompatible|
| |authenticated access mode. | intranets using | with Linux |
| |(That is anonymous access | NT/2000/XP servers| servers by |
| |disabled, or Access Control | in authenticated | definition. |
| |Lists enabled) | access mode. | |
| | | | - Does not |
| |Use in combination with | | work on the |
| |authentication "none", as the | | Internet. |
| |authentication is already done| | |
| |by IIS during the session | | - Does not |
| |initiation. | | allow |
| | | | anonymous |
| | | | browsing. |
| | | | |
+---------+------------------------------+--------------------+----------------+
|omni |The users identity is queried | | |
| |AND validated by an Omnicron | | |
| |OmniHTTPd web server. | - For users of | - For users of|
| | | Omnicron OmniHTTPd| Omnicron |
| |Use in combination with | web servers. | OmniHTTPd web |
| |authentication "none", as | | servers. |
| |authentication is already done| | |
| |by OmniHTTPd during the | | |
| |session initiation. | | |
+---------+------------------------------+--------------------+----------------+
|remote_ |The user's identity is | | |
|user |determined by reading the | | |
| |REMOTE_USER environment | - For users that | - Requires a |
| |variable. | already have an | web server |
| |Use in combination with | wider auth. | setup that |
| |authentication "none", as | scheme that sets | sets |
| |authentication has already | REMOTE_USER, allows| REMOTE_USER. |
| |been done by the system that | MRBS to use that | Could be hard |
| |sets REMOTE_USER | scheme | to set up |
+---------+------------------------------+--------------------+----------------+
|ip |Users are identified by the IP| | |
| |address of their computer. | | |
| | | - Easy to setup, | - Incompatible|
| |Use in combination with | for MRBS | with DHCP. |
| |authentication "none" or | evaluation. | |
| |"config". | | - Users cannot|
| | | | make changes |
| | | | from a |
| | | | different |
| | | | computer. |
| | | | |
+---------+------------------------------+--------------------+----------------+
|host |Users are identified by the | | |
| |DNS name of their host | | |
| |computer. | - Easy to setup, | - Users cannot|
| | | for MRBS | make changes |
| |Use in combination of | evaluation. | from a |
| |authentication "none" or | | different |
| |"config". | | computer. |
| | | | |
+---------+------------------------------+--------------------+----------------+
|joomla |Use when using Joomla! | | |
| |authentication. | | |
| | | | |
+---------+------------------------------+--------------------+----------------+
|wordpress|Use when using WordPress | | |
| |authentication. | | |
| | | | |
+---------+------------------------------+--------------------+----------------+
|cas |Use when using CAS | - Federated login | - Requires a |
| |authentication. | - Single signon | CAS server |
| | | - Single signoff | |
+---------+------------------------------+--------------------+----------------+
|saml |Use when using SAML | - Federated login | - Must set up |
| |authentication. | - Single signon | SimpleSamlPhp|
| | | - Single signoff | - SAML |
| | | - Hooks into | knowledge |
| | | SAML infra | recommended |
+---------+------------------------------+--------------------+----------------+
How to configure authentication
===============================
Users
-----
You don't configure users in MRBS. Users (and their password) are configured in
an external authentication server.
Exceptions:
- The "config" authentication is managed by MRBS, using a list of names and
passwords in config.inc.php. This is done by specifying: $auth["user"][
"username1"] = "password1"; $auth["user"]["username2"] = "password2";
etc
- The "db" authentication is managed by MRBS, using a list of names and
passwords stored in the MRBS database.
Administrators
--------------
Prerequisite: Administrators are also users. They must have a valid user name
and password in the selected authentication server.
Administrators are defined in config.inc.php. This is done by specifying:
$auth["admin"][] = "username1";
$auth["admin"][] = "username2";
etc
You can have as many administrators as you want in this list.
Exceptions:
- In the "db" authentication method, access rights are stored in the MRBS
database and are managed by MRBS.
The default MRBS configuration uses PHP sessions, and a user list in
config.inc.php for authentication. It defines three demo users 'alice' 'bob'
and 'administrator'. The 'administrator' user is also in the administrators
list by default. You will almost surely want to change these.
If IP authentication is used, for "username" use the IP address.
In this case, make sure to define the local host (127.0.0.1) as an
administrator. This allows to conveniently administer the reservation system
locally on the server.
Session type
------------
Choose one type in the list above, and set the $auth["session"] parameter in
config.inc.php. Example:
$auth["session"] = "php";
Authentication type
-------------------
Choose the internal authentication module you want.
Internal PHP modules
--------------------
If it's an internal PHP module, set the $auth["type"] parameter in
confing.inc.php. Example:
$auth["type"] = "pop3";
Then set the type-specific parameters in config.inc.php. See details in the
authentication descriptions below.
External programs
-----------------
If you want to use an external authentication program, set $auth["type"] =
"ext"; and set the additional parameters:
- The name of the selected program in $auth["prog"].
Don't forget to prefix it with "./" under Unix and ensure that the
program is executable by the "user" that the webserver runs as.
Example:
$auth["prog"] = "./cryt_passwd.pl";
- The arguments to pass to the above program in $auth["params"].
$auth["params"] = "passwd_file #USERNAME# #PASSWORD#";
At runtime "#USERNAME#" and "#PASSWORD#" will get replaced with the username
and password that the user entered to login. The string can contain other
arguments in addition to the above two.
Internal PHP Authentication Modules Configuration
=================================================
Config Authentication
---------------------
Config Authentication uses no external server. It uses a list of users
config.inc.php. Configure it as follows:
$auth["type"] = "config";
Then add the list of users:
$auth["user"]["username1"] = "password1";
$auth["user"]["username2"] = "password2";
etc
Note: If the password contains the characters \ or $, then it's necessary to
prefix them with a \. For example for password pa$$word, use the string =
"pa\$\$word".
Finally put at least one of the users in the administrator's list.
$auth["admin"][] = "username2";
etc
DB Authentication
-------------------
Authentication method, usable on the Internet.
It works by storing the list of users in a new table called mrbs_users in
the mrbs database. The authentication is done by the class \MRBS\Auth\AuthDb.
Enable it by setting $auth["type"]="db" in config.inc.php.
The list of users is displayed by clicking on the "Users" menu item in the
top banner. This list is managed by module edit_users.php. Administrators
have the right to edit every entry, and add or remove users. Ordinary users
only have the right to edit their own entry.
When you first run MRBS it will prompt you to set up a user with administrator
rights. Until you do this the system is open and the first person to use MRBS
will be able to set up an administrator and lock you out of the system. You
will then only be able to get back into the system by emptying the users
table.
Once you have set up the first administrator you can then log on to the system
using the username and password you have just created and create more users.
Upgrading from pre-1.4.2 systems:
Versions of MRBS before 1.4.2 did not store access rights in the database
and relied on the list of admins in the config file. If you are upgrading
from a pre-1.4.2 system, MRBS will automatically upgrade the users table in the
database by adding a field for access rights level and give admin rights to
those users for whom admin access is defined in the config file. So, if
upgrading, you will need to make sure that your admins are set in the config
file until you have run edit_users.php (by following the "User list" link) for
the first time. Once you have run edit_users.php the admin definitions in the
config file are no longer used and can be deleted if you wish.
It's possible, and very simple, to add new application-specific fields in
the mrbs_users table. No change is needed to the MRBS code. It will automatically
detect the new fields and add columns for them. You can turn the field names
into meaningful labels by using the $vocab_override config setting, eg
$vocab_override['en']['address'] = 'Postal address';
Future improvements
- Have a second level of administrators (level 3 users), with only such
level 3 users allowed to edit the user database. This would be similar to
all other authentications in mrbs, which delegate the user accounts
management to an external authority.
External DB (db_ext) Authentication
-----------------------------------
Authentication method, usable on the Internet.
It works by using one of the installer's own databases. The database can
be any database system for which MRBS has a database abstraction. You can
configure how to connect to the database server, what kind of database
system it is (mysql, mysqli, pgsql currently), the database/table to
use and the names of the "user" and "password" columns.
The configuration items are held in config.inc.php and are as follows:
$auth['db_ext']['db_system'] = 'mysql'; /* Or 'mysqli', 'pgsql' */
$auth['db_ext']['db_host'] = 'localhost';
The server to connect to.
$auth['db_ext']['db_username'] = 'authuser';
$auth['db_ext']['db_password'] = 'authpass';
The MySQL username and password to connect with.
$auth['db_ext']['db_name'] = 'authdb';
The name of the database.
$auth['db_ext']['db_table'] = 'users';
The table that holds the authentication data.
$auth['db_ext']['column_name_username'] = 'name';
$auth['db_ext']['column_name_password'] = 'password';
The names of the two columns that hold the authentication data.
$auth['db_ext']['password_format'] = 'md5';
This is the format of the password entries in the table. You can specify
'md5', 'sha1', 'sha256', 'crypt' or 'plaintext'.
$auth['db_ext']['column_name_level'] = 'level';
This configuration item is optional and contains the name of the column
that hold the access level of the user.
POP3 Authentication
-------------------
MRBS has POP3 Authentication support. This method will first try to
authenticate using APOP, and fall back to standard USER/PASS if that
fails. This can be used by setting config.inc.php as follows:
$auth["type"] = "pop3";
Also you will need to change the section:
# 'auth_pop3' configuration settings
# Where is the POP3 server
$pop3_host = "pop3-server-name";
# The POP3 server port
$pop3_port = "110";
You will almost certainly not need to change the POP3 port number.
This method supports authentication against multiple servers using
the syntax below:
Multiple servers all using the same port:
# 'auth_pop3' configuration settings
# Where is the POP3 server
$pop3_host[] = "localhost";
$pop3_host[] = "myisp.co.uk";
# The POP3 server port
$pop3_port = "110";
Multiple servers with the option of different ports for each server:
# 'auth_pop3' configuration settings
# Where is the POP3 server
$pop3_host[] = "localhost";
$pop3_host[] = "myisp.co.uk";
# The POP3 server ports in the same order as the hosts
$pop3_port[] = "110";
$pop3_port[] = "110";
Note: if you use the latter configuration then an equal number of hosts
and ports must be specified or authentication will fail.
IMAP Authentication
--------------------
Very similar in principle to the pop3 authentication.
MRBS has IMAP Authentication support. This can be used by setting
config.inc.php as follows:
$auth["type"] = "imap";
Also you will need to change the section:
# 'auth_imap' configuration settings
# Where is the IMAP server
$imap_host = "imap-server-name";
# The IMAP server port
$imap_port = "143";
You will almost certainly not need to change the IMAP port number.
This method supports authentication against multiple servers using
the syntax below. It will try all the servers until a match is found
or it fails to authenticate the user.
Multiple servers all using the same port:
# 'auth_imap' configuration settings
# Where is the IMAP server
$imap_host[] = "localhost";
$imap_host[] = "myisp.co.uk";
# The IMAP server port
$imap_port = "143";
Multiple servers with the option of different ports for each server:
# 'auth_imap' configuration settings
# Where is the IMAP server
$imap_host[] = "localhost";
$imap_host[] = "myisp.co.uk";
# The IMAP server ports in the same order as the hosts
$imap_port[] = "143";
$imap_port[] = "143";
Note: if you use the latter configuration then an equal number of hosts
and ports must be specified or authentication will fail.
LDAP Authentication
-------------------
This method uses PHP's LDAP extension which must be compiled into PHP
or installed and loaded as a plugin extension in your php.ini.
This method can be used by setting config.inc.php as follows:
$auth["type"] = "ldap";
Also you will need to change the section:
# 'auth_ldap' configuration settings
# Where is the LDAP server
$ldap_host = "localhost";
# If you have a non-standard LDAP port, you can define it here
#$ldap_port = 389;
# If you want to use LDAP v3, change the following to true
$ldap_v3 = false;
# If you want to use TLS, change following to true
$ldap_tls = false;
# LDAP base distinguish name
# See AUTHENTICATION for details of how check against multiple base dn's
$ldap_base_dn = "ou=organizationalunit,dc=my-domain,dc=com";
# Attribute within the base dn that contains the username
$ldap_user_attrib = "uid";
You only need to set $ldap_port if your LDAP server uses a non-standard
port.
If you want to use LDAP v3, or TLS over LDAP set $ldap_v3 or $ldap_tls
to true, respectively.
This method will attempt an authenticated bind to the ldap server using
the supplied password and a distinguished name, which is formed from the
base distinguished name, the user attribute and the user name.
This method supports multiple values for most of the configuration
parameters, including $ldap_base_dn entries and $ldap_user_attrib
values. The authentication is attempted with each set of configuration
parameters in turn until it succeeds or it fails to authenticate the user.
Multiple base distinguished names with the same user attribute for each
base dn:
# 'auth_ldap' configuration settings
# Where is the LDAP server
$ldap_host = "localhost";
# LDAP base distinguish names
$ldap_base_dn[] = "ou=People, o=myCompany, c=US";
$ldap_base_dn[] = "ou=Administrators, o=myCompany, c=US";
#
$ldap_user_attrib = "uid";
Multiple base distinguished names with the option of different user attributes
for each base dn:
# 'auth_ldap' configuration settings
# Where is the LDAP server
$ldap_host = "localhost";
# LDAP base distinguish names
$ldap_base_dn[] = "ou=People, o=myCompany, c=US";
$ldap_base_dn[] = "ou=Administrators, o=myCompany, c=US";
#
$ldap_user_attrib[] = "uid";
$ldap_user_attrib[] = "cn";
Note: if you use the latter configuration then an equal number of base dn's
and user attributes must be specified or authentication will fail.
NT Authentication
-----------------
MRBS has Microsoft Windows NT/IIS authentication support. This can be used by
setting config.inc.php as follows:
$auth["session"] = "nt";
$auth["type"] = "none";
Note that technically NT authentication is actually an MRBS session scheme. We
put it in this list as it is related with authentication anyway.
To add an admin, just add his user's Windows user account like this:
$auth["admin"][] = "nt_username";
Also this scheme is fairly simple (it relies on IIS determining a user's
Windows user account identity, before allowing the user to establish a network
connection with the server) there are some requirements for it to work (these
notes are based on IIS 5.0):
- You have to configure you mrbs directory (at least) to use either
'Basic Authentication' or 'Integrated Windows Authentication' (formerly
called NTLM or Windows NT Challenge/Response authentication).
To enable a WWW authentication method in IIS:
In the Internet Information Services snap-in, select your site, but preferably
only mrbs directory, and open its property sheets. Select the Directory
Security property sheet. Under Anonymous Access and Authentication Control,
click Edit. In the Authentication Methods dialog box, select one or more
appropriate methods.
The simplest way is to use 'Integrated Windows Authentication' because unlike
'Basic authentication', it does not prompt users for a user name and password.
The current Windows user information on the client computer is used for the
'integrated Windows authentication'. It is also a more secure form of
authentication because the user name and password are not sent across the
network.
But if you really want your users to enter their domain username/password, you
have to select 'Basic Authentication'. The advantage of Basic authentication is
that it is part of the HTTP specification, and is supported by most browsers.
So, theoretically, you can log in with a valid domain username/password with a
non-Microsoft browser, but frankly I did not tested it. The disadvantage is
that 'Basic authentication' transmit passwords in an unencrypted form.
- To use 'Integrated Windows Authentication', you HAVE TO use the
Microsoft browser too. Currently, only Internet Explorer, version 2.0 and
later, supports this.
- The 'Anonymous access' must be disabled.
- If you enable both Basic and Integrated authentication, Integrated
authentication takes precedence over Basic authentication.
- 'Integrated Windows authentication' does not work over HTTP Proxy
connections or other firewall applications. So this scheme is more suitable
for an Intranet, but 'Basic Authentication' should work (not tested).
All this was tested against IIS 5.0 on Windows 2000 server and Windows 2000
workstations using Internet Explorer 6.0, but this should work from IIS 4.0.
OMNI Authentication
--------------------
OMNI Authentication using Omnicron OmniHTTPd web server security features.
Very similar in principle to NT authentication.
$auth["session"] = "omni";
$auth["type"] = "none";
Note that technically Omni authentication is actually an MRBS session scheme.
We put it in this list as it is related with authentication anyway.
REMOTE_USER Authentication
--------------------------
Get user identity/password using the REMOTE_USER environment variable
To use this session scheme, set in config.inc.php:
$auth['session'] = 'remote_user';
$auth['type'] = 'none';
If you want to display a logout link, set in config.inc.php:
$auth['remote_user']['logout_link'] = '/logout/link.html'
Joomla! Authentication
----------------------
Set in config.inc.php
$auth['joomla']['rel_path'] = '..'; // Path to the Joomla! installation relative to MRBS.
// [Note that although in Joomla! access levels are solely used for what users are allowed to *see*, we use
// them in MRBS to determine what they can see and do, ie we map them onto MRBS user levels. While this
// does not strictly follow the Joomla! access control model, it does make it much simpler to give users
// MRBS permissions.]
// List of Joomla! viewing access level ids that have MRBS Admin capabilities. You can if you wish use
// the existing viewing access levels. However we recommend creating a new access level, eg
// "MRBS Administrator" and assigning that to user groups, as it will then be clearer which groups
// have what kind of access to MRBS.
$auth['joomla']['admin_access_levels'] = array(); // Can either be a single integer, or an array of integers.
// As above, but for ordinary user rights. Create for example a viewing access level called "MRBS User"
// and assign that level to user groups as appropriate.
$auth['joomla']['user_access_levels'] = array(); // Can either be a single integer, or an array of integers.
WordPress Authentication
------------------------
Set in config.inc.php
$auth['session'] = 'wordpress';
$auth['type'] = 'wordpress';
$auth['wordpress']['rel_path'] = '..'; // Path to the WordPress installation relative to MRBS.
// List of WordPress roles that have MRBS Admin capabilities. The default is 'administrator'.
// Note that these role names are the keys used to store the name, which are typically in lower case
// English, eg 'administrator', and not the values which are displayed on the dashboard form, which will
// generally start with a capital and be translated, eg 'Administrator' or 'Administrateur' (French),
// depending on the site language you have chosen for WordPress.
// You can define more than one WordPress role that maps to the MRBS Admin role by using
// an array. The comment below assumes that you have created a new WordPress role (probably by using
// a WordPress plugin) called "MRBS Admin", which will typically (depending on the plugin) have a key of
// 'mrbs_admin', and that you assigned that role to those users that you want to be MRBS admins.
$auth['wordpress']['admin_roles'] = 'administrator'; // can also be an array, eg = array('administrator', 'mrbs_admin');
// List of WordPress roles that have MRBS User capabilities. This allows you to have some WordPress users
// who are authorised to use MRBS and some who are not.
$auth['wordpress']['user_roles'] = array('subscriber', 'contributor', 'author', 'editor', 'administrator');
Then in your WordPress wp-config.php file set:
// Define cookie paths so that login cookies can be shared with MRBS
$domain_name = 'example.com'; // Set to your domain name
define('COOKIEPATH', '/');
define('SITECOOKIEPATH', '/');
// In the definition below the '.' is necessary for older browsers (see
// http://php.net/manual/en/function.setcookie.php).
define('COOKIE_DOMAIN', ".$domain_name");
define('COOKIEHASH', md5($domain_name));
SAML Authentication
-------------------
Set in config.inc.php
$auth['type'] = 'saml';
$auth['session'] = 'saml';
$auth['saml']['ssp_path'] = '/opt/simplesamlphp';
$auth['saml']['authsource'] = 'default-sp';
$auth['saml']['attr']['username'] = 'sAMAccountName';
$auth['saml']['attr']['mail'] = 'mail';
$auth['saml']['admin']['memberOf'] = ['CN=Domain Admins,CN=Users,DC=example,DC=com'];
// Optional access control filter
$auth['saml']['user']['memberOf'] = ['CN=Calendar Users,CN=Users,DC=example,DC=com'];
This scheme assumes that you've already configured SimpleSamlPhp, that
you have configured oid2name mapping, and that you have set up aliases
in your webserver so that SimpleSamlPhp can handle incoming assertions.
Refer to the SimpleSamlPhp documentation for more information on how to
do that.
https://simplesamlphp.org/docs/stable/simplesamlphp-install
https://simplesamlphp.org/docs/stable/simplesamlphp-sp
Wix Authentication
-------------------
See wix/README
External Authentication Programs Configuration
==============================================
Encrypted password authentication
-------------------------------
crypt_passwd.pl is a short Perl script, which can be used to demonstrate
how the "ext" authentication provider works.
It utilises uses a file containing usernames and their encrypted passwords.
config.inc.php should be changed to have a section that reads something like:
$auth["type"] = "ext";
$auth["prog"] = "../crypt_passwd.pl";
$auth["params"] = "/etc/httpd/mrbs_passwd #USERNAME# #PASSWORD#";
As you can see the crypt_passwd.pl script takes 3 parameters.
The first parameter is the filename of the password file.
It must be readable by the user which PHP is running as, which is usually the
user the web server is running as. The password file must consist of pairs of
username and encrypted password, separated by a colon. See crypt_passwd.example
for an example password file.
NOTE: Under Unix, make sure crypt_passwd.pl has execution rights: 'chmod +x
crypt_passwd.pl'
PAM Authentication
--------------------
In case your Unix system uses PAM (especially Linux, but also SUN Solaris)
you might try the script auth_pam.pl. This script takes two two parameters -
the user name and the user password.
This perl script requires Authen::PAM.
The script has to be run as SUID. Therefore you should take some precautions
to not undermine your system's security. Change the group of the script to that
of your Web Server (for Apache this is normally nobody or apache) and don't
make it readable and executable to anybody else, eg.:
chgrp nobody auth_pam.pl
The script has to be run SUID and has to be executed by sperl:
chmod 4750 auth_pam.pl
The first line (#!/usr/bin/sperl5.6.0) says where sperl is located on
your system. Please adapt this for your needs.
Now add the configuration to web/config.inc.php in your MRBS directory.
This looks as follows (adapt the path to auth_pam.pl according to your
your configuration):
$auth["realm"] = "MY REALM";
$auth["type"] = "ext";
$auth["prog"] = "/var/www/html/mrbs/auth_pam.pl";
$auth["params"] = "#USERNAME# #PASSWORD#";
That's it.
Note that this has been only tested with Red Hat 7.x. Feedback on whether this
works on other systems ( eg. Solaris) is appreciated.
Creating a new authentication scheme
====================================
Authentication classes are responsible for validating user/password pairs.
They must not attempt to communicate with the user.
Adding support for a new authentication service not yet supported by MRBS can
be done using one of the two following techniques:
Adding a PHP class
------------------
You must create a new filed called "web/lib/MRBS/Auth/AuthXxx.php".
It will be configured by setting in config.inc.php:
$auth["type"] = "xxx";
Underscores in the config variable need a CamelCase name. For example
$auth["type"] = "xxx_yyy";
requires a file called AuthXxxYyy.php
The class should extend \MRBS\Auth\Auth
Using an external program
-------------------------
External authentication programs are invoked via the internal PHP configuration
proxy class called "AuthExt".
The external program must take the username, password, and possibly other
values as parameters. Its exit code must be a zero for "OK", and anything else
for "not OK".
AuthExt takes the following parameters in config.inc.php:
$auth["type"] = "ext";
$auth["prog"] = "the_pathname_of_your_program";
$auth["params"] = "the arguments your program needs";
AuthExt constructs a command line to execute like:
$cmd = $auth["prog"] . ' ' . $auth["params"];
$cmd = preg_replace('/#USERNAME#/',$user,$cmd);
$cmd = preg_replace('/#PASSWORD#/',$pass,$cmd);
This should allow a lot of flexibility with different authenticators.
Creating a new session scheme
==============================
Session classes manage the user interface for obtaining the user name and
password. They also manage the way the name and password are recorded
throughout a session.
To create a new scheme, you must create a new PHP class called
"web/lib/MRBS/Session/SessionXxx.php".
It will be configured by setting in config.inc.php:
$auth["session"] = "xxx";
Underscores in the config variable need a CamelCase name. For example
$auth["session"] = "xxx_yyy";
requires a file called SessionXxxYyy.php
The session class should extend either \MRBS\Session\SessionWithLogin or
\MRBS\Session\SessionWithoutLogin.
Note: Session schemes are also useful in the case where a web server enforces
its own session and authentication management. See the SessionNt.php and
session SessionOmni.php files as examples. In this case, use in combination
with authentication "none", as the real authentication is already done during
the session initiation, and needs not be done again inside MRBS.
A little bit of history
=======================
The original version of MRBS, created by Daniel Gardner, did not have
username/password support. Each booking that was made had the IP address of the
client machine logged as the "creator" of the booking.
In this case the IP address functions as the "username".
This works well in the case where all IPs are static, and everyone is allowed
access to the system. In the wider world there are occasions where this is a
little too liberal.
To combat this MRBS 0.8 introduced authentication, initially provided by Sam
Mason <smason@mtc.ricardo.com>.
There are three levels of access in MRBS:
- Level 0 - not logged in
- Level 1 - Authenticated
- Level 2 - Administrator
The administrators are allowed to modify other people's bookings, whereas Level
1 users can only change their own. Administrators also have the ability to add
and remove rooms and areas.
With time, several alternative authentication methods were introduced.
All rely on the same basic principles:
- Each user is identified by a name.
- Each name has a corresponding password.
- The name/password pair must be valid in the authentication service
MRBS connects to.
- Some users have additional MRBS administration rights. Their names
are listed in the $auth["admin"] list in config.inc.php.
- It's the web site creator's responsibility to manually enter the
names of all the users that will have administrator rights in this list.
Before accessing a restricted page, MRBS prompts the user for a name and
password. Then it connects to an authentication server, which is responsible
for deciding if the user/password pair is valid. If it is, MRBS finally grants
access to the page.
The types of authentication servers supported are: LDAP servers; NT domain
controllers; Netware servers; POP3 email servers; IMAP email servers; etc.
Still the initial authentication system had shortcomings:
- The user/password prompt relied on the HTTP basic authentication
protocol, in a mode not supported by IIS web servers.
- MRBS was increasingly used on the Internet, where central
authentication servers are not available in the general case.
- There was no way to log off.
In MRBS 1.2, the authentication system was restructured by Jean-François
Larvoire <jf.larvoire@sf.net>
The main change was to separate the user/password acquisition (Also called
session initiation), from its validation (called authentication).
The existing routines for querying the user identity were moved to module
session_http.inc (now SessionHttp.php). This module is left in for backwards
compatibility, but deprecated. A new session management module was introduced,
based on PHP's built-in session management. This is the one recommended now on.
It includes the ability to log off.
On the authentication side, most existing modules were carried on, with the
session code removed. A simple module, auth_config.inc (now AuthConfig.php) was
added, managing a simple list of users in config.inc.php. Eventually there will
also be another authentication module, using a table of users in the MRBS
database.
