%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 [[Passwords | 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]].


!! Activating AuthUser

To activate PmWiki's identity-based system, add the following line
to ''local/config.php'':

    include_once("$FarmD/scripts/authuser.php");


!! Creating user accounts

Most of AuthUser's configuration is performed via the [[Site.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 Site.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 Site.AuthUser page cannot easily determine the passwords stored in the page.  

->%note% For greater security, [[Site.AuthUser?action=attr | place a read password]] on the Site.AuthUser page.

To change or reset an account's password, simply replace the encrypted string with another @@[=(:=]encrypt:)@@ directive.


!! Controlling access to pages by login

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 that has successfully logged in, use "[@id:*@]".

One can also perform site-wide restrictions based on identity in the $DefaultPasswords array: e.g.

    # require valid login before viewing pages
    $DefaultPasswords['read'] = 'id:*';
    # Alice and carol may edit
    $DefaultPasswords['edit'] = 'id:alice,carol';
    # All admins and Fred may edit
    $DefaultPasswords['edit'] = array('@admins', 'id:Fred');

You can change the $DefaultPasswords array in local customization files such as:
* local/config.php (for entire wiki)
* farmconfig.php (for entire wikifarm)


!! [[#auth_groups]] Organizing accounts into groups

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 Site.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.

!!! Excluding individuals from password groups

Group password memberships are maintained by editing the Site.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 Site.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@]".


!! Getting account names and passwords from external sources

The AuthUser script has the capability of obtaining username/password pairs from places other than the Site.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 (.htpasswd/.htgroup)

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 Site.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 Site.AuthUser like:

    htgroup: /path/to/.htgroup

    
!!! Configuration via ''local/config.php''

AuthUser configuration settings can also be made from the ''local/config.php'' file in addition to the Site.AuthUser page.  Such settings are placed in the $AuthUser array, and ''must be set prior to including the ''authuser.php'' script''. Some examples:

    # set a password for alice
    $AuthUser['alice'] = crypt('wonderland');
    # set a password for carol
    $AuthUser['carol'] = '$1$CknC8zAs$dC8z2vu3UvnIXMfOcGDON0';
    # define the @editors group
    $AuthUser['@editors'] = array('alice', 'carol', 'bob');
    # Use local/.htpasswd for usernames/passwords
    $AuthUser['htpasswd'] = 'local/.htpasswd';
    # Use local/.htgroup for group memberships
    $AuthUser['htgroup'] = 'local/.htgroup';


!!! Configuration via LDAP

Authentication can be performed via an external LDAP server -- simply set an entry for "ldap" in either Site.AuthUser or the ''local/config.php'' file.

    # use ldap.airius.com for authentication
    $AuthUser['ldap'] = 'ldap://ldap.airius.com/ou=People,o=Airius?cn?sub';

LDAP authentication in AuthUser closely follows the model used by Apache 2.0's [[http://httpd.apache.org/docs/2.0/mod/mod_auth_ldap.html|mod_auth_ldap]] module; see especially the documentation for  [[http://httpd.apache.org/docs/2.0/mod/mod_auth_ldap.html#authldapurl|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.

!! Setting the Author Name
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;

!! See Also

* [[PmWiki.Passwords]]
* [[PmWiki.PasswordsAdmin]]
* [[Cookbook:AuthUser]] for tips and tricks
* [[Site.AuthUser]]

%trail%<<|[[Documentation Index]]|>>

>>faq<< [[#faq]]

Q:  Can I specify authorization group memberships from with ''local/config.php''?

A:  You can as of version 2.1.14 -- simply put the group definition into the $AuthUser array:

        $AuthUser['@editors'] = array('alice', 'carol', 'bob');