version=pmwiki-2.2.74 ordered=1 urlencoded=1
author=Petko
charset=UTF-8
csum=pmcrypt
name=PmWiki.AuthUser
rev=191
targets=PmWiki.Passwords,PmWiki.ThoughtsOnAccessControl,Cookbook.QuickStartForAuthUser,PmWiki.PasswordsAdmin,SiteAdmin.AuthUser,PmWiki.AuthUser,Cookbook.AuthUserViaMicrosoftLDAP,Cookbook.AuthUser,Cookbook.UserLastAction,PITS.00400,Cookbook.HtpasswdForm
text=(:Summary:Authorization system that uses usernames and passwords:)%0a(:Audience: administrators (intermediate) :)%0aAuthUser 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.%0a%0aAuthUser 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]].%0a%0aSee also:  [[Cookbook:Quick Start for AuthUser]].%0a%0a!! Activating AuthUser%0aTo activate PmWiki's identity-based system, add the following line%0ato ''local/config.php'':%0a%0a    include_once("$FarmD/scripts/authuser.php");%0a%0aEnsure that you have [[PasswordsAdmin | set a site wide admin password]], otherwise you will not be able to edit [[SiteAdmin.AuthUser]].%0a%0a->%25note%25 Note: Older versions of PmWiki (before 2.2.0-beta58) use ''Site.AuthUser''.%0a%0aPmWiki caches some group and page authorization levels when a page is accessed. For this reason, it is better to include @@authuser.php@@ quite early in config.php, notably%0a* after any recipe which inserts some custom writable PageStore class (MySQL, SQLite, Compressed PageStore or other)%0a* and after any internationalization (UTF-8 and XLPage).%0a%0a(If you don't use a custom PageStore class and i18n, include @@authuser.php@@ first thing in @@config.php@@.)%0a%0aAll other recipes should be included after these.%0a%0a!! Creating user accounts%0aMost 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).%0a%0aTo create a login account, simply add lines to SiteAdmin.AuthUser that look like:%0a%0a    username: [=(:=]encrypt ''password'':)%0a%0aFor example, to create a login account for "alice" with a password of "wonderland", enter:%0a%0a    alice: [=(:=]encrypt wonderland:)%0a%0aWhen 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.  %0a%0aTo change or reset an account's password, simply replace the encrypted string with another @@[=(:=]encrypt:)@@ directive.%0a%0a%25note%25 The password cannot contain spaces, tabs, new lines, columns ":" and equals "="; on some systems it should contain at least 4 characters. Usernames and passwords are case sensitive, eg. "User" is not the same as "user".%0a%0a!! Controlling access to pages by login%0a%0aPages 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@]".%0a%0aIt'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":%0a%0a    quick id:alice,carol%0a%0aTo allow access to anyone who has successfully logged in, use "[@id:*@]".%0a%0aOne can also perform site-wide restrictions based on identity in the $DefaultPasswords array: e.g.%0a%0a    # require valid login before viewing pages%0a    $DefaultPasswords['read'] = 'id:*';%0a    # Alice and carol may edit%0a    $DefaultPasswords['edit'] = 'id:alice,carol';%0a    # All admins and Fred may edit%0a    $DefaultPasswords['edit'] = array('@admins', 'id:Fred');%0a%0aYou can change the $DefaultPasswords array in local customization files such as:%0a* local/config.php (for entire wiki)%0a* farmconfig.php (for entire wikifarm)%0a%0a!! [[#auth_groups]] Organizing accounts into groups%0a%0aAuthUser 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:%0a%0a    @writers: alice, bob%0a    carol: @writers, @editors%0a    @admins: alice, dave%0a    %0aThen, 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.%0a%0a!!! Excluding individuals from password groups%0a%0aGroup 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:%0a%0a    @wholeoffice: *%0a%0aIf you need to keep "Fred" out of this password group :%0a%0a    @wholeoffice: *,-Fred%0a%0aTo allow all users except Fred to change page attributes, for example, you can add to config.php :%0a    $DefaultPasswords['attr'] = array('id:*,-Fred');%0a%0a(:if authid:)%0a>>clip%3c%3c%0a!!!!!Wiki Debug%0a* %25newwin%25 [[Diagnostics -> {$Name}?action=diag]]%0a* %25newwin%25 [[PHPInfo -> {$Name}?action=phpinfo]]%0a>>%3c%3c%0a(:ifend:)%0a%0a!! Getting account names and passwords from external sources%0a%0aThe 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|LDAP]] servers, or even the ''local/config.php'' file.%0a%0a!!! Passwd-formatted files (.htpasswd/.htgroup)%0a%0aPasswd-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:%0a%0a    alice:vK99sgDV1an6I%0a    carol:Q1kSeNcTfwqjs%0a%0aTo 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:%0a%0a    htpasswd: /path/to/.htpasswd%0a%0aCreation 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:%0a%0a    $ htpasswd /path/to/.htpasswd alice%0a    New password:%0a    Re-type new password:%0a    Adding password for user alice%0a    $%0a%0aSimilarly, 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.%0a%0a    writers: carol%0a    editors: alice carol bob%0a    admins: alice dave%0a%0aNote 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:%0a%0a    htgroup: /path/to/.htgroup%0a%0a!!! Configuration via ''local/config.php''%0a%0aAuthUser 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:%0a%0a    # set a password for alice%0a    $AuthUser['alice'] = pmcrypt('wonderland');%0a    # set a password for carol%0a    $AuthUser['carol'] = '$1$CknC8zAs$dC8z2vu3UvnIXMfOcGDON0';%0a    # define the @editors group%0a    $AuthUser['@editors'] = array('alice', 'carol', 'bob');%0a    # Use local/.htpasswd for usernames/passwords%0a    $AuthUser['htpasswd'] = 'local/.htpasswd';%0a    # Use local/.htgroup for group memberships%0a    $AuthUser['htgroup'] = 'local/.htgroup';%0a%0a[[#LDAP]]%0a!!! Configuration via LDAP%0a%0aAuthentication can be performed via an external LDAP server -- simply set an entry for "ldap" in either SiteAdmin.AuthUser or the ''local/config.php'' file.%0a%0a    # use ldap.airius.com for authentication%0a    $AuthUser['ldap'] = 'ldap://ldap.airius.com/ou=People,o=Airius?cn?sub';%0a%0aMake sure to include AuthUser below the entry for the ldap server:%0a%0a    # Want to use AuthUser so we can use ldap for passwords%0a    include_once("$FarmD/scripts/authuser.php");%0a%0aAnd remember to assign the Security Variables for edit and history (or whatever):%0a%0a    #Security Variables set login for edit & history page%0a    # to let anyone edit that has an ldap entry:%0a    $HandleAuth['diff'] = 'edit';%0a    $DefaultPasswords['edit'] = 'id:*';%0a    $Author = $AuthId;%0a%0aLDAP 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.%0a%0aFor servers that don't allow anonymous binds, AuthUser provides $AuthLDAPBindDN and $AuthLDAPBindPassword variables to specify the binding to be used for searching.%0a%0aSee also [[Cookbook:AuthUser via Microsoft LDAP]]%0a%0a!! Setting the Author Name%0aBy 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 in config.php to activate AuthUser:%0a%0a    include_once("$FarmD/scripts/authuser.php");%0a    $Author = $AuthId; # after include_once()%0a%0aTo 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:%0a[@%0a    include_once("$FarmD/scripts/author.php");%0a    include_once("$FarmD/scripts/authuser.php");%0a    if ($Author) {%0a	if (strstr($Author, '-') != false) {%0a	    $Author = "$AuthId-" . preg_replace('/^[^-]*-/', '', $Author);%0a	} else if ($Author != $AuthId) {%0a	    $Author = $AuthId . '-' . $Author;%0a	} else {%0a	    $Author = $AuthId;%0a	}%0a    } else {%0a	$Author = $AuthId;%0a    }%0a    $AuthorLink = "[[~$Author]]";%0a@]%0aThe 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-".%0aThe reason why $AuthorLink needs to be set is that, if it isn't, the RecentChanges page will have the wrong link in it.%0a%0a!!! Removing the "Author" edit field%0aTo force users to edit with their AuthID instead of having a field they can place any name in. This enables administration to keep track of who is doing what better. This line also links the Author name to their Profile.\\%0aGo to Site.EditForm, remove the line\\%0a[@$[Author]: (:input e_author:)@]\\%0aor replace it with\\%0a[@$[Author]: [[Profiles/{$Author}]]@]\\%0a%0a!! Authorization, Sessions, and WikiFarms [[#sessions]]%0a%0aPmWiki 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.%0a%0aWhat 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:%0a%0a-->[@session_name('XYZSESSID');@]%0a%0aThe XYZSESSID can be any unique name (letters only is safest).%0a%0a!! See Also%0a%0a* [[PmWiki.Passwords]]%0a* [[PmWiki.PasswordsAdmin]]%0a* [[Cookbook:AuthUser]] for tips and tricks%0a* [[SiteAdmin.AuthUser]]%0a%0a%0a>>faq%3c%3c [[#faq]]%0aQ:  Can I specify authorization group memberships from with ''local/config.php''?%0a%0aA:  Yes -- put the group definition into the $AuthUser array (in config.php):%0a%0a        $AuthUser['@editors'] = array('alice', 'carol', 'bob');%0a%0aQ: Can I have multiple admin groups?%0a%0aA: Yes, define the groups with @@ array('@admins', '@moderators'); @@ like this:%0a%0a  $DefaultPasswords['admin'] = array( pmcrypt('masterpass'), # global password%0a    '@admins', '@moderators', # +users in these groups%0a    'id:Fred', 'id:Barney');  # +users Fred and Barney%0a%0aQ:  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?%0a%0aA:  This is caused by the way that PHP treats sessions.  See [[PmWiki.AuthUser#sessions]] for more details.%0a%0aQ: 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.%0a%0aA: See [[Cookbook:UserLastAction]].%0a%0aQ: Though every setting seems correct, authentication against LDAP is not working. There is nothing in ldap log, what's wrong?%0a%0aA: Be sure ldap php module is installed ( on debian apt-get install php(4|5)-ldap ; apache(2)ctl graceful )%0a%0aQ: The login form asks for username and password, but only password matters.  %0a-> Username can be left blank and it still signs in under the account.  Is this intentional and if so, can I change it so that the username and password must both be entered?  - X 1/18/07  Never mind I think this has something to do with using the admin password.  I created a test account and it's working ok.%0a%0aA: Make sure you are not entering the admin password when testing the account because, if the password is equal to the admin password, it will authenticate directly through the config.php file and skip any other system.%0a%0aA: Do note that even with AuthUser activated you can still log in with a blank username and only entering the password.  In that case any password you enter will be "accepted" but only passwords which authenticate in the given context will actually give you any authorization rights.  Using this capability AuthUser comfortably coexists with the default password-based system.%0a%0aIf you want to require both username and password, then you need to set an admin id '''before''' including authuser.php:%0a%0a[@%0a## Define usernames and passwords.%0a$AuthUser['carol'] = '$1$CknC8zAs$dC8z2vu3UvnIXMfOcGDON0';%0a%0a## Enable authentication based on username.%0ainclude_once('scripts/authuser.php');%0a%0a# $DefaultPasswords['admin'] = pmcrypt('secret');%0a$DefaultPasswords['admin'] = 'id:carol';%0a@]%0a%0aA username and password will then be required before login is successful.%0a%0aQ: Is there any way to hide IP addresses once someone has logged in so that registered users can keep their IP addresses invisible to everyone except administrators?  - X 1/18/07%0a%0aA: Yes, see solution provided at PITS:00400.%0a%0aQ: Is there a way that people could self-register through AuthUser?  %0a%0aA: You can see [[(Cookbook:)HtpasswdForm]] for a recipe providing this feature. %0a%0aQ: I would like it that after I have AuthUser turned and a user is authenticated to get on my site, that if I have a password put on a particular page or group that they don't get the AuthUser form to show up (username and password), but only the typical field for password?%0a%0aA: See [[this thread of the mailing list -> http://article.gmane.org/gmane.comp.web.wiki.pmwiki.user/52420]]. %0a
time=1430064860
