[[PageOutline(2-5,content)]] = Cookbook: AccountManagerPlugin configuration = commented sample configurations for most common and some special use cases We collect some useful configuration examples here giving 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, but will get (re-)written all-lowercase, if added/updated via the Trac admin web-UI. As you see, case doesn't really matter here. == Basic configuration/Kickstart == !AccountManagerPlugin replaces the traditional Trac login feature with a webform, because [wiki:AccountManagerPlugin/Modules#LoginModule LoginModule] is enabled in all examples below. No additional action is required since acct_mgr-0.4, but older plugin versions required to disable the obsoleted Trac core component explicitly: {{{ #!cfg [components] trac.web.auth.loginmodule = disabled }}} === !HtPasswdStore === {{{ #!cfg [account-manager] password_store = HtPasswdStore htpasswd_hash_type = md5 ;password_file = /var/trac/trac.htpasswd ; old style (acct_mgr < 0.4) htpasswd_file = /var/trac/trac.htpasswd ; new style (acct_mgr >= 0.4) 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 }}} 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) ''Note:'' new configuration option 'htpasswd_file' for acct_mgr-0.4 and later see [wiki:AccountManagerPlugin/AuthStores#HtPasswdStore HtPasswdStore] module documentation for more details === !HtDigestStore === {{{ #!cfg [account-manager] password_store = HtDigestStore htdigest_realm = Trac ;password_file = /var/trac/trac.htdigest ; old style (acct_mgr < 0.4) htdigest_file = /var/trac/trac.htdigest ; new style (acct_mgr >= 0.4) 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 }}} 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`' ''Note:'' new configuration option 'htdigest_file' for acct_mgr-0.4 and later see [wiki:AccountManagerPlugin/AuthStores#HtDigestStore HtDigestStore] module documentation for more details === !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 }}} 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`' ''Note:'' new configuration option 'db_htdigest_realm' for acct_mgr-0.4 and later see [wiki:AccountManagerPlugin/AuthStores#SessionStore SessionStore] module documentation for more details === Create users === Create the first user through browser-based registration enabled by following additional lines in `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 priviledges to the first user you created. === Award an existing user account for Trac admin === {{{ #!sh trac-admin /path/to/env permission add TRAC_ADMIN permission list }}} === Goodies === There are some misc 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 YMMV.||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 per-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. This is, a user checks a "Remember Me" checkbox on the [wiki:AccountManagerPlugin/Modules#LoginModule login page] and, next time he 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 for acct_mgr-0.4. 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: {{{ #!cfg [trac] auth_cookie_path = /var/www/trac }}} Hint: 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 change. 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-explaining in the way how 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: Tab. 1: lock time progression (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: Tab. 2: lock time progression (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