[[PageOutline(2-5,Contents,pullout)]]

= Cookbook: AccountManagerPlugin configuration

{{{#!box note
This page documents AccountManagerPlugin 0.4 and later with Trac 0.11 and later. If you are using older versions, please upgrade.
}}}

This page lists some useful configuration examples with hints on proper use of available options.

'''General hints:'''
 * Content for different section grouped in one example must be used together.
 * Option names are written in !CamelCase style notation in this !CookBook, but will get (re-)written to lowercase under the hood once added/updated via the Trac admin web user interface.

== Basic configuration

The !AccountManagerPlugin replaces the traditional Trac login feature with a webform, because [wiki:AccountManagerPlugin/Modules#LoginModule LoginModule] is enabled in all examples below.

=== !HtPasswdStore

{{{#!cfg
[account-manager]
password_store = HtPasswdStore
htpasswd_hash_type = md5
htpasswd_file = /var/trac/trac.htpasswd
reset_password = false
}}}
{{{#!cfg
[components]
acct_mgr.admin.* = enabled
acct_mgr.api.* = enabled
acct_mgr.db.sessionstore = disabled
acct_mgr.htfile.htdigeststore = disabled
acct_mgr.htfile.htpasswdstore = enabled
acct_mgr.http.* = disabled
acct_mgr.notification.* = enabled
acct_mgr.pwhash.* = disabled
acct_mgr.register.* = enabled
acct_mgr.svnserve.svnservepasswordstore = disabled
acct_mgr.web_ui.* = enabled
acct_mgr.web_ui.resetpwstore = disabled
trac.web.auth.loginmodule = disabled
}}}
will:
 * enable required AccountManagerPlugin core components
 * enable [wiki:AccountManagerPlugin/AuthStores#HtPasswdStore HtPasswdStore] module for file-based password store in ''htpasswd'' format
 * select this store as the only active one
 * use `md5` password hash type for changed/new passwords, hint: use the cryptographically strongest, that is available on your system (and still compatible with other applications in shared-use case)

=== !HtDigestStore

{{{#!cfg
[account-manager]
password_store = HtDigestStore
htdigest_realm = Trac
htdigest_file = /var/trac/trac.htdigest
reset_password = false
}}}
{{{#!cfg
[components]
acct_mgr.admin.* = enabled
acct_mgr.api.* = enabled
acct_mgr.db.sessionstore = disabled
acct_mgr.htfile.htdigeststore = enabled
acct_mgr.htfile.htpasswdstore = disabled
acct_mgr.http.* = disabled
acct_mgr.notification.* = enabled
acct_mgr.pwhash.* = disabled
acct_mgr.register.* = enabled
acct_mgr.svnserve.svnservepasswordstore = disabled
acct_mgr.web_ui.* = enabled
acct_mgr.web_ui.resetpwstore = disabled
trac.web.auth.loginmodule = disabled
}}}
will:
 * enable required AccountManagerPlugin core components
 * enable [wiki:AccountManagerPlugin/AuthStores#HtDigestStore HtDigestStore] module for file-based password store in ''htdigest'' format
 * select this store as the only active one
 * set realm to select relevant htdigest file entries to '`Trac`'

=== !SessionStore

{{{#!cfg
[account-manager]
hash_method = HtDigestHashMethod
db_htdigest_realm = TracDB
password_store = SessionStore
reset_password = false
}}}
{{{#!cfg
[components]
acct_mgr.admin.* = enabled
acct_mgr.api.* = enabled
acct_mgr.db.sessionstore = enabled
acct_mgr.htfile.* = disabled
acct_mgr.http.* = disabled
acct_mgr.notification.* = enabled
acct_mgr.pwhash.htdigesthashmethod = enabled
acct_mgr.pwhash.htpasswdhashmethod = disabled
acct_mgr.register.* = enabled
acct_mgr.svnserve.svnservepasswordstore = disabled
acct_mgr.web_ui.* = enabled
acct_mgr.web_ui.resetpwstore = disabled
trac.web.auth.loginmodule = disabled
}}}
will:
 * enable required AccountManagerPlugin core components
 * enable [wiki:AccountManagerPlugin/AuthStores#SessionStore SessionStore] module for Trac db based password store in ''htdigest'' format
 * enable `HtDigestHashMethod`, the implicitly default hash method for this store
 * select this store as the only active one
 * set realm to select relevant htdigest entries to '`TracDB`'

=== Create users

Create the first user through browser-based registration enabled by following additional lines in the `components` section of `trac.ini`:
{{{#!cfg
[components]
acct_mgr.register.* = enabled
}}}

Don't add another `components` section, just the configuration line with 'enabled' into an existing `components` section. After user creation you may choose to disable registration by uncommenting the [AccountManagerPlugin#RegistrationModule RegistrationModule] setting above or changing it to:
{{{#!cfg
[components]
;need this for first user
acct_mgr.register.* = disabled
}}}
Or just use the plugins admin page form Trac's web interface, after you've given admin privileges to the first user you created.

=== Grant an existing user account for Trac admin

{{{#!sh
trac-admin /path/to/env permission add <username> TRAC_ADMIN permission list <username>
}}}

=== Goodies

There are some miscellaneous options for `account-manager` section of `trac.ini` you may want to set/unset depending on your requirements:
||'''Option'''||'''Default Value'''||'''Recommendation'''||'''Available Since'''||
||reset_password || True ||Disallow password reset if needed. ||acct_mgr-0.? ||
||generated_password_length ||8 ||Useful only with reset enabled. Raise the bar for brute-force attacks on user passwords, if you feel this is needed. [AccountManagerPlugin#AccountGuard AccountGuard] might still be a more powerful alternative, see [#AccountLocking Account Locking] section below. ||acct_mgr-0.? ||
||force_passwd_change ||True ||Useful only with reset enabled. Randomly generated passwords should be motivation enough to change them, but this depends on local policy.||acct_mgr-0.? ||

See the paragraphs below for a more detailed explanation of some of these settings.

== Advanced configurations

=== Password Reset

You need an authentication store enabled and configured correctly as a pre-requisite here. Additionally explicitly enable or unset the following option:
{{{#!cfg
[account-manager]
;reset_password = false
}}}
{{{#!cfg
[components]
acct_mgr.notification.accountchangelistener = enabled
acct_mgr.pwhash.htdigesthashmethod = enabled
acct_mgr.web_ui.accountmodule = enabled
acct_mgr.web_ui.resetpwstore = enabled
}}}
enables password reset for both, admin (for everyone) and regular users (only for their own account).
A detailed explanation of the [wiki:AccountManagerPlugin/Modules#Lostpasswordprocedure 'lost password' procedure] is available too.

'''Note:''' Hiding of non-functional parts from the web-UI has been corrected for acct_mgr-0.4.1, and the plugin complains on misconfiguration too, see trac.log.

=== Persistent Sessions

{{{#!cfg
[account-manager]
persistent_sessions = true
}}}
will allow users to be remembered across sessions without needing to re-authenticate. That is, a user checks a "Remember Me" checkbox on the [wiki:AccountManagerPlugin/Modules#LoginModule login page] and, next time the user visits the site, he/she will be remembered.

=== Single Sign On

In a setup with multiple Trac environments per domain/host chances are that users want to work with several projects simultaneously. 40 and more environments served by a single Trac install have been reported from private networks as well as seen on the web.

To address the demand for authentication information sharing between some/all of the Trac environments in such a setup a login synchronization process has been introduced. It relies on a non-default value for the path of `trac_auth` and `trac_auth_session` cookies. Otherwise the cookie wouldn't be recognized as related to different Trac environments by the web browser client.

In order to achieve this, set `auth_cookie_path` in the `[trac]` section of your `trac.ini` file to the '''URL''' path of your installations `TRAC_PARENT_DIR`. Assumed your projects use the URL `http://www.example.com/trac/<project_name>`, this should look like:
{{{#!cfg
[trac]
auth_cookie_path = /trac
}}}

If you made this change to an existing setup and encounter login problems afterwards, check the cookies stored in your browser. If it holds any `trac_auth` cookies with a path other than the one defined by `auth_cookie_path`, you might have to remove those as they might conflict.

'''Note''': Even if this setting has been introduced in Trac 0.12, it could be set in `trac.ini` for older Trac versions, and !AcctMgr will use it, specifically providing a cookie path fix-up for `trac_auth` cookies generated by Trac 0.11 and above.

An inherited `trac.ini` file is perfect for sharing this common setting and more between several Trac environments. Additionally delete existing `trac_auth` browser cookies. This is a one-time cleanup and only necessary to avoid unexpected login results after a cookie path changes. Of course logging out in one Trac environment will terminate the authenticated session for all participants sharing authentication as indicated by the equal cookie path setting. A mixed setup containing both authentication sharing and non-sharing environments side-by-side is valid and works well.

=== Account Locking

 * new feature since acct_mgr-0.3
 * available options (displayed with default values here):

{{{#!cfg
[account-manager]
login_attempt_max_count = 0
user_lock_time = 0
user_lock_max_time = 86400
user_lock_time_progression = 1
}}}
{{{#!cfg
[components]
acct_mgr.guard.accountguard = enabled
}}}
but this does '''nothing''' for backwards-compatibility, preventing surprises for unaware plugin-upgraders.

As long as login_attempt_max_count == 0, login failure tracking is actually disabled and no other related option matters. The account locking section in the configuration admin panel (since acct_mgr-0.4.1) is quite self-explanatory in the way it conditionally hides irrelevant options. So it's worth a look even for the console guru, who doesn't immediately understand these options.

==== Hard Lock-up

{{{#!cfg
[account-manager]
login_attempt_max_count = 5
user_lock_time = 0
}}}
will have following effect:
 * lock account after 5 successive failed login attempts
 * no lock expiration, so release strictly '''requires administrator interaction'''

==== Fixed login retry delay

Fixed delay time regardless of number of successive failed login attempts.

{{{#!cfg
[account-manager]
login_attempt_max_count = 3
user_lock_time = 30
}}}
will have following effect:
 * lock account after 3 successive failed login attempts
 * release account lock 30 seconds after last failed login attempt

==== Modestly progressing login retry delay

{{{#!cfg
[account-manager]
login_attempt_max_count = 2
user_lock_time = 15
user_lock_max_time = 0
user_lock_time_progression = 2
}}}
will have following effect:
 * first account lock after 2 successive failed login attempts
 * timed account locked release after a time, that depends on failed login attempt history like so:

'''Table 1''': lock time progression with factor 2:
||attempt count ||delay time in seconds ^![1]^||
||0 ||0
||1 ||1 s ||
||2 ||15 s ||
||3 ||30 s ||
||4 ||60 s ||
||5 ||2 min ||
||6 ||4 min ||
||7 ||8 min ||
||8 ||16 min ||
||9 ||32 min ||
||10 ||1h 4 min ||
||.. ||.. ||
||18 ||1 d 12 h 25 min||
||.. ||.. ||
||26 ||1 a 23 d ||
||.. ||.. ||

^![1]^ time after previous failed login attempt

==== Aggressively progressing, but limited login retry delay

{{{#!cfg
[account-manager]
login_attempt_max_count = 4
user_lock_time = 10
user_lock_max_time = 86400
user_lock_time_progression = 5
}}}
will have following effect:
 * first account lock after 4 successive failed login attempts
 * timed account locked release after a time, that depends on failed login attempt history and is limited to max. 24 hours like so:

'''Table 2''': lock time progression with factor 5:
||attempt count ||delay time in seconds ||
||0 ||0 ||
||1 ||10 s ||
||2 ||25 s ||
||3 ||2 min 5 s ||
||4 ||10 min 25 s ||
||5 ||4 h 20 min ||
||6 ||21 h 42 min ||
||7 ||24 h ^![2]^||
||8 ||24 h ||
||9 ||24 h ||
||.. ||.. ||

^![2]^ limit kicking in here and on any further attempt