(:Summary:Authorization system that uses usernames and passwords:)
%audience% administrators (intermediate)
AuthUser is PmWiki's identity-based authorization system that allows access to pages to be controlled through the use of usernames and passwords. AuthUser can be used in addition to the password-based scheme that is PmWiki's default configuration.
AuthUser is a very flexible system for managing access control on pages, but flexibility can also bring complexity and increased maintenance overhead to the wiki administrator. This is why PmWiki defaults to the simpler password-based system. For some thoughts about the relative merits of the two approaches, see PmWiki:ThoughtsOnAccessControl.
See also: Cookbook:Quick Start for AuthUser
To activate PmWiki's identity-based system, add the following line
to local/config.php:
include_once("$FarmD/scripts/authuser.php");
Ensure that you have set a site wide admin password, otherwise you will not be able to edit SiteAdmin.AuthUser.
->%note% Note: Older versions of PmWiki (before 2.2.0-beta58) use Site.AuthUser.
Most of AuthUser's configuration is performed via the SiteAdmin.AuthUser page. To change the AuthUser configuration, simply edit this page like any other wiki page (you'll typically need to use the site's admin password for this).
To create a login account, simply add lines to SiteAdmin.AuthUser that look like:
username: (:encrypt password:)
For example, to create a login account for "alice" with a password of "wonderland", enter:
alice: (:encrypt wonderland:)
When the page is saved, the "(:encrypt wonderland:)" part of the text will be replaced by an encrypted form of the password "wonderland". This encryption is done so that someone looking at the SiteAdmin.AuthUser page cannot easily determine the passwords stored in the page.
To change or reset an account's password, simply replace the encrypted string with another (:encrypt:) directive.
Pages and groups can be protected based on login account by using "passwords" of the form id:username in the password fields of ?action=attr (see PmWiki.Passwords). For example, to restrict a page to being edited by Alice, one would set the password to "id:alice".
It's possible to use multiple "id:" declarations and passwords in the ?action=attr form, thus the following setting would allow access to Alice, Carol, and anyone who knows the password "quick":
quick id:alice,carol
To allow access to anyone who has successfully logged in, use "id:*".
One can also perform site-wide restrictions based on identity in the $DefaultPasswords array: e.g.
You can change the $DefaultPasswords array in local customization files such as:
AuthUser also makes it possible to group login accounts together into authorization groups, indicated by a leading "@" sign. As with login accounts, group memberships are maintained by editing the SiteAdmin.AuthUser page. Group memberships can be specified by either listing the groups for a login account (person belongs to groups) or the login accounts for a group (group includes people). You can repeat or mix-and-match the two kinds as desired:
@writers: alice, bob
carol: @writers, @editors
@admins: alice, dave
Then, to restrict page access to a particular group, simply use "@group" as the "password" in ?action=attr or the $DefaultPasswords array, similar to the way that "id:username" is used to restrict access to specific login accounts.
Group password memberships are maintained by editing the SiteAdmin.AuthUser page. To specify a password group that allows access to anyone who is authenticated, you can specify:
@wholeoffice: *
If you need to keep "Fred" out of this password group, you might try:
@wholeoffice: *, -Fred
... but this does %red%not%% work. You can, however, get the desired result by using the first setting (@wholeoffice: *) on the SiteAdmin.AuthUser page and then setting the password for the page or group you wish to protect in ?action=attr or the $DefaultPasswords array to "id:*, -Fred".
The AuthUser script has the capability of obtaining username/password pairs from places other than the SiteAdmin.AuthUser page, such as passwd-formatted files (usually called '.htpasswd' on Apache servers), LDAP servers, or even the local/config.php file.
Passwd-formatted files, commonly called .htpasswd files in Apache, are text files where each line contains a username and an encrypted password separated by a colon. A typical .htpasswd file might look like:
alice:vK99sgDV1an6I
carol:Q1kSeNcTfwqjs
To get AuthUser to obtain usernames and passwords from a .htaccess file, add the following line to SiteAdmin.AuthUser, replacing "/path/to/.htpasswd" with the filesystem path of the .htpasswd file:
htpasswd: /path/to/.htpasswd
Creation and maintenance of the .htpasswd file can be performed using a text editor, or any number of other third-party tools available for maintaining .htpasswd files. The Apache web server typically includes an htpasswd command for creating accounts in .htpasswd:
$ htpasswd /path/to/.htpasswd alice
New password:
Re-type new password:
Adding password for user alice
$
Similarly, one can use .htgroup formatted files to specify group memberships. Each line has the name of a group (without the "@"), followed by a colon, followed by a space separated list of usernames in the group.
writers: carol
editors: alice carol bob
admins: alice dave
Note that the groups are still "@writers", "@editors", and "@admins" in PmWiki even though the file doesn't specify the @ signs. To get AuthUser to load these groups, use a line in SiteAdmin.AuthUser like:
htgroup: /path/to/.htgroup
AuthUser configuration settings can also be made from the local/config.php file in addition to the SiteAdmin.AuthUser page. Such settings are placed in the $AuthUser array, and must be set prior to including the authuser.php script. Some examples:
Authentication can be performed via an external LDAP server -- simply set an entry for "ldap" in either SiteAdmin.AuthUser or the local/config.php file.
LDAP authentication in AuthUser closely follows the model used by Apache 2.0's mod_auth_ldap module; see especially the documentation for AuthLDAPUrl for a description of the url format.
For servers that don't allow anonymous binds, AuthUser provides $AuthLDAPBindDN and $AuthLDAPBindPassword variables to specify the binding to be used for searching.
By default, PmWiki will use a login name in the Author field of the edit form, but allows the author to change this value prior to saving. To force the login name to always be used as the author name, use the following sequence to activate AuthUser:
include_once("$FarmD/scripts/authuser.php");
$Author = $AuthId;
To allow more flexibility, but still enable changes to be linked to the authorized user, one can give the author name a prefix of the $AuthId instead:
include_once("$FarmD/scripts/author.php");
include_once("$FarmD/scripts/authuser.php");
if ($Author) {
if (strstr($Author, '-') != false) {
$Author = "$AuthId-" . preg_replace('/^[^-]*-/', '', $Author);
} else if ($Author != $AuthId) {
$Author = $AuthId . '-' . $Author;
} else {
$Author = $AuthId;
}
} else {
$Author = $AuthId;
}
$AuthorLink = "[[~$Author]]";
The above will allow the user to put in the author name of their choice, but that will always be replaced by that name prefixed with "$AuthId-".
The reason why $AuthorLink needs to be set is that, if it isn't, the RecentChanges page will have the wrong link in it.
PmWiki uses PHP sessions to keep track of any user authorization information. By default PHP is configured so that all interactions with the same server (as identified by the server's domain name) are treated as part of the same session.
What this means for PmWiki is that if there are multiple wikis running within the same domain name, PHP will treat a login to one wiki as being valid for all wikis in the same domain. The easiest fix is to tell each wiki to have use a different "session cookie". Near the top of a wiki's local/config.php file, before calling authuser or other recipes, add a line like:
-->session_name('XYZSESSID');
The XYZSESSID can be any unique name (letters only is safest).
%trail%<<|Documentation Index|>>
Q: I get http error 500 "Internal Server Error" when I try to log in. What's wrong?
A: This can happen if the encrypted passwords are not created on the web server that hosts the PmWiki.
The crypt function changed during the PHP development, e.g. a password encrypted with PHP 5.2 can not be decrypted in PHP 5.1, but PHP 5.2 can decrypt passwords created by PHP 5.1.
This situation normally happens if you prepare everything on your local machine with the latest PHP version and you upload the passwords to a webserver which is running an older version.
The same error occurs when you add encrypted passwords to local/config.php.
Solution: Create the passwords on the system with the oldest PHP version and use them on all other systems.
Q: Can I specify authorization group memberships from with local/config.php?
A: Yes -- put the group definition into the $AuthUser array:
$AuthUser['@editors'] = array('alice', 'carol', 'bob');
Q: I'm running multiple wikis under the same domain name, and logins from one wiki are appearing on other wikis. Shouldn't they be independent?
A: This is caused by the way that PHP treats sessions. See PmWiki.AuthUser for more details.
Q: How can I access the authorization groups that the current user belongs to in order to test using that as a condition of an if statement?
Q: Is there any way to have groups inherit other groups (e.g. @fruits: @apples, @oranges, jack)?
Q: Is it possible to list more than one .htpasswd and .htgroup file to be used? e.g. if I am running a wikifarm and some users are common across various fields, it would be nice if they only needed to update their password once. Sure I could merge all the passwd & group files, but then I wouldn't be able to support identical user or group names on each independent wikifield..
Q: Is there any way to record the time of the last login for each user when using AuthUser? I need a way to look for stale accounts.
A: I wrote a recipe to do something like this. It records the last action for each user (not necessarily just login actions). See Cookbook:UserLastAction for more info. --Lordmundi March 23, 2007
Q: I want to allow anyone to edit my wiki, but don't want anyone else to use my name as the author. Is there a way to "reserve" and password protect certain usernames? Or basically just require a password when attempting to edit a page with a registered user's name in the author field?