Cookbook: AccountManagerPlugin configuration

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 LoginModule is enabled in all examples below.

HtPasswdStore

[account-manager]
password_store = HtPasswdStore
htpasswd_hash_type = md5
htpasswd_file = /var/trac/trac.htpasswd
reset_password = false

[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 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

[account-manager]
password_store = HtDigestStore
htdigest_realm = Trac
htdigest_file = /var/trac/trac.htdigest
reset_password = false

[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 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

[account-manager]
hash_method = HtDigestHashMethod
db_htdigest_realm = TracDB
password_store = SessionStore
reset_password = false

[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 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:

[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 RegistrationModule setting above or changing it to:

[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

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. AccountGuard might still be a more powerful alternative, see 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:

[account-manager]
;reset_password = false

[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 '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

[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 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:

[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):

[account-manager]
login_attempt_max_count = 0
user_lock_time = 0
user_lock_max_time = 86400
user_lock_time_progression = 1

[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

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

[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

[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

[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