Help

How to authenticate against an LDAP server

LDAP authentication is set up in exactly the same way as for the standard Pmwiki authentication module AuthUser: add a line of one of the following forms to your local/config.php.

$AuthUser['ldap'] = 'ldap://host:port/basedn';
$AuthUser['ldap'] = 'ldap://host:port/basedn?attribute';
$AuthUser['ldap'] = 'ldap://host:port/basedn?attribute?scope';
$AuthUser['ldap'] = 'ldap://host:port/basedn?attribute?scope?filter';

attribute will default to 'uid', scope to 'one', and filter to have no filtering applied. See PmWiki.AuthUser and AuthLDAPUrl for more information.

What wildcards can be good for

The wildcards make it possible to let users more easily control which access modes are associated with the pages that they are newly creating. For example setting a rd_*.*Public entry allows users to make pages publicly readble by just having their page names end on "Public". Similiar we can have -rd_*.*Internal or ed_*.*Open. It is straight forward. Note that these rights have to be set in the GuestUsers record, such that everybody enjoys them.

How to create personally accessible pages

Basically, have a permission table in the LoggedInUsers record looking like:

rd_MyWiki.{$AuthId},
ed_MyWiki.{$AuthId},
up_MyWiki.{$AuthId},
hi_MyWiki.{$AuthId}

and make sure that the MyWiki page group is forbidden for the general user.

Ip based silent permission granting

The module makes it possible to silently give rights to clients based on their ip address. Silently means that the rights are granted in parallel to and independent of the authentication-based rights. Besides the authentication status of the client is by no means altered on observing it in a certain ip range.

To grant clients of a certain ip range special rights, create a group using that ip range as name, and add the desired rights as usual to its permission table. Valid ip ranges are for example

 12.
 12.168.
 12.168.1.
 12.168.1.10

which all would match the client ip 12.168.1.10. (At least the first byte must be given, and it must end with a dot unless all four bytes are given.)

Ip based login restrictions

As additional security measure it might be useful to check for authenticating some user whether the client is located in a certain (allowed) ip range. For this just add a comma-separated list of ip ranges (of the format as above) in the "Permit login from IPs only" field of that user. (For the 'admin' user this restriction must be hardcoded using the $UA2AdminLoginFromIpsOnly variable.)

Change default redirections after login/logout

By default the client is redirected after login to the page he wanted to access before being redirected to the login page for lack of sufficient privileges, or the page he looked at before wanting to login himself, or to the home page if none of these applies. After logout the client is redirected at the login page by default.

For changing this behaviour, set the variables

 $UA2AfterSILoginRedirectTo
 $UA2AfterLogoutRedirectTo

to the wiki pages you like as target. You can use the string "{$AuthId}" in $UA2AfterSILoginRedirectTo which is replaced by the attained user name upon login, making it possible to redirect to personal pages within the wiki.

Persistent logins

... can be enabled by setting $UA2AllowCookieLogin to true. $UA2CookieExpireTime controls after which time (even) the authentication cookie expires (in seconds). For example, include the following in your config.php file:

$UA2AllowCookieLogin=true;               // allow persistent logins
$UA2CookieExpireTime=60*60*24*7;         // for up to 7 days
include("$FarmD/cookbook/userauth2.php");

Protection against brute force attacks

... is controlled via $UA2EnableBruteForceProtect (default: enabled). Ensures that in any time frame of $FailedLoginsTimeframeUser seconds that has seen more than $FailedLoginsLimitUser failed login attempts with a certain username no further login attempt is possible. Same with the client ip address:

SDV($FailedLoginsLimitUser,       100);
SDV($FailedLoginsTimeframeUser,   30*86400); // in secs; default: 30 days
SDV($FailedLoginsLimitIp,         100);
SDV($FailedLoginsTimeframeIp,     30*86400);

What is this parent field about when creating/editing a user?

This module makes it possible to delegate admin tasks, for example creating users, granting permissions to them (but in principal all of them), to other users. To this end the users are organized in a hierarchical way by assigning to each of them a parent, with the admin the "root" parent. See below for details. (If you don't need delegation, just ignore the field.)

How to introduce new permission levels for certain actions, like "publish", "comment" etc.

In your local/config.php, define

$HandleAuth['publish']     = 'publish'; // this remaps the action "publish" to new level "publish"
$UA2LevelToAbbr['publish'] = 'pb';      // this defines an abbreviation to be used in perm tables
$UA2PageRelatedLevelAbbr['publish'] = 'pb';      // this marks it as page related

before the inclusion of userauth2.php. To keep some standard in level abbreviation naming I suggest using

hi for "history"
pb for "publish"
cm for "comment"
a.s.o. (add yours here)

How to change one's own password as a user

While logged in, call the pmwiki standard action ?action=pwchange for changing your password. Thanks to metahacker. (Passwords for "owned" users can be changed within the admin tool.)

How to create a new user as a non-admin user

Specify cu in the user's permission record. See help in the admin tool (below the permission records) also.

How to use the recipe with SSL

Simply use the instructions at Cookbook.SwitchToSSLMode. UA2 handles https transparently correctly - there should be no further changes necessary.

Note: SwitchToSSLMode facilitates automatic protocol switching based on detection of certain actions, pages or other criteria hinting a need for security.

Delegation mechanism

Basic mechanism

The delegation capability starts with the idea that every user can create further users below ("children") that then have maximally the same rights as their generator. To this end every user is assigned a parent on its creation, with the 'admin' being the root in this hierarchy. The parent will then usually grant permissions using a permission table, which on evaluation are masked to a maximum of the parent's own rights.

Now since it might be useful also for indirect parents to grant rights directly to some user, a permission record can be extended to consist of more than one permission table (one for each "patron" granting). (Set $UA2AllowMultipleGranters to true in your local config to make this possible.) In this case it is sensible to make sure that the permissions granted to the user are masked by the permissions of the respective granter. The resulting set of permissions give by each granter is then combined independently, i.e. with logic "or".

Further one might allow to create new users which are associated to another parent than oneself. This way a user can be assigned to be administered by some intermediate supervisor (as seen from the admin).

To ensure that a user is indeed correctly confined to his rights, some rules govern the possible actions that modify or query the whole permission setup. Most importantly any user can obviously edit permissions only for users/groups strictly below himself. The parent that may be set on creation of a user must also be below or at most equal to the creating user, otherwise it would be possible for the creator to grant more rights than he himself possesses and then exploit them by switching to the new identity. In the same way, though less obvious, it is implemented that membership to a group is honoured only if granted by someone who is (indirect) parent of the group.

For the complete set of rules governing permission evaluation and change, have a look in the Implementation Reference below, sections "Permission evaluation process" and "Rest -> perm semantics". In doubt contact me for details.

Usage

Grant the level ad to give the user access to the admin tool, grant cu to enable him to create or delete users (or groups), eu to edit user's (or group's) permissions. The level ip must be given if also ip related settings shall be allowed to be modified. Usually no actions are allowed on the guest user group or logged in user group.

Independent of the admin tool are the profile (yet non-existent) and the password change. To give access to these grant pr or pw, respectively. Given pw the user is allowed to change his own password. Granting the level ps however enables the user to set passwords for all users below him.

For digging into some example setups, have a look here.

Questions

Q: Where does one set the values for the various variables mentioned above, e.g. for $FailedLoginsLimitUser etc.?

A: UserAuth2 sets the default values for all these variables with the Pmwiki SDV() construct. Therefore, to override them, just set them in your $FarmD/local/config.php. ThomasP October 02, 2008, at 01:07 PM

Q1: When successfully adding new user (or after any other successfull action) I always getting page with text "No input file specified." Is there any way to avoid this? userauth-2.2.2, Windows, Abyss web server, Script, Referer and Cookies not blocked.

Q2: What should the link "Profile" in Admin tool do? To redirect to Profiles.? It returns me to the page I called Admin tool from (even if I create profile page for an user and I can read/write to it), but I probably didn't set something up (Never used profiles yet) [I too can't figure this one out...Dave 12_5_2011]

Q3: It seems that user "admin" cant change attributes to any pages in my case ("Insufficient privileges to perform action."), what can be wrong? Or it's normal?