Changes between Version 21 and Version 22 of CookBook/AccountManagerPluginConfiguration
- Timestamp:
- Jul 22, 2015, 8:47:10 AM (9 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
CookBook/AccountManagerPluginConfiguration
v21 v22 1 [[PageOutline(2-5,content)]] 2 3 = Cookbook: AccountManagerPlugin configuration = 4 commented sample configurations for most common and some special use cases 5 6 We collect some useful configuration examples here giving hints on proper use of available options. 7 8 '''General hints:''' 1 [[PageOutline(2-5,Contents,pullout)]] 2 3 = Cookbook: AccountManagerPlugin configuration 4 5 This page lists some useful configuration examples with hints on proper use of available options. 6 7 '''General hints:''' 9 8 * Content for different section grouped in one example must be used together. 10 9 * 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. 11 10 12 == Basic configuration/Kickstart == 11 == Basic configuration/Kickstart 12 13 13 !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: 14 {{{ 15 #!cfg 14 {{{#!cfg 16 15 [components] 17 16 trac.web.auth.loginmodule = disabled 18 17 }}} 19 18 20 === !HtPasswdStore ===21 {{{ 22 #!cfg19 === !HtPasswdStore 20 21 {{{#!cfg 23 22 [account-manager] 24 23 password_store = HtPasswdStore … … 28 27 reset_password = false 29 28 }}} 30 {{{ 31 #!cfg 29 {{{#!cfg 32 30 [components] 33 31 acct_mgr.admin.* = enabled … … 50 48 * 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) 51 49 52 ''Note:'' new configuration option 'htpasswd_file' for acct_mgr-0.4 and later 53 see [wiki:AccountManagerPlugin/AuthStores#HtPasswdStore HtPasswdStore] module documentation for more details 54 55 === !HtDigestStore === 56 {{{ 57 #!cfg 50 '''Note:''' new configuration option 'htpasswd_file' for acct_mgr-0.4 and later, see [wiki:AccountManagerPlugin/AuthStores#HtPasswdStore HtPasswdStore] module documentation for more details. 51 52 === !HtDigestStore 53 54 {{{#!cfg 58 55 [account-manager] 59 56 password_store = HtDigestStore … … 63 60 reset_password = false 64 61 }}} 65 {{{ 66 #!cfg 62 {{{#!cfg 67 63 [components] 68 64 acct_mgr.admin.* = enabled … … 85 81 * set realm to select relevant htdigest file entries to '`Trac`' 86 82 87 ''Note:'' new configuration option 'htdigest_file' for acct_mgr-0.4 and later 88 see [wiki:AccountManagerPlugin/AuthStores#HtDigestStore HtDigestStore] module documentation for more details 89 90 === !SessionStore === 91 {{{ 92 #!cfg 83 '''Note:''' new configuration option 'htdigest_file' for acct_mgr-0.4 and later, see [wiki:AccountManagerPlugin/AuthStores#HtDigestStore HtDigestStore] module documentation for more details. 84 85 === !SessionStore 86 87 {{{#!cfg 93 88 [account-manager] 94 89 hash_method = HtDigestHashMethod … … 97 92 reset_password = false 98 93 }}} 99 {{{ 100 #!cfg 94 {{{#!cfg 101 95 [components] 102 96 acct_mgr.admin.* = enabled … … 120 114 * set realm to select relevant htdigest entries to '`TracDB`' 121 115 122 '' Note:'' new configuration option 'db_htdigest_realm' for acct_mgr-0.4 and later123 see [wiki:AccountManagerPlugin/AuthStores#SessionStore SessionStore] module documentation for more details 124 125 === Create users === 116 '''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. 117 118 === Create users 119 126 120 Create the first user through browser-based registration enabled by following additional lines in `components` section of `trac.ini`: 127 {{{ 128 #!cfg 121 {{{#!cfg 129 122 [components] 130 123 acct_mgr.register.* = enabled … … 132 125 133 126 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: 134 {{{ 135 #!cfg 127 {{{#!cfg 136 128 [components] 137 129 ;need this for first user 138 130 acct_mgr.register.* = disabled 139 131 }}} 140 Or just use the plugins admin page form Trac's web interface, after you've given admin privile dges to the first user you created.141 142 === Award an existing user account for Trac admin ===143 {{{ 144 #!sh132 Or just use the plugins admin page form Trac's web interface, after you've given admin privileges to the first user you created. 133 134 === Award an existing user account for Trac admin 135 136 {{{#!sh 145 137 trac-admin /path/to/env permission add <username> TRAC_ADMIN permission list <username> 146 138 }}} 147 139 148 === Goodies === 149 There are some misc options for `account-manager` section of `trac.ini` you may want to set/unset depending on your requirements: 140 === Goodies 141 142 There are some miscellaneous options for `account-manager` section of `trac.ini` you may want to set/unset depending on your requirements: 150 143 ||'''Option'''||'''Default Value'''||'''Recommendation'''||'''Available Since'''|| 151 144 ||reset_password || True ||Disallow password reset if needed. ||acct_mgr-0.? || 152 145 ||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.? || 153 ||force_passwd_change ||True ||Useful only with reset enabled. Randomly generated passwords should be motivation enough to change them, but YMMV.||acct_mgr-0.? ||146 ||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.? || 154 147 155 148 See the paragraphs below for a more detailed explanation of some of these settings. 156 149 157 == Advanced configurations == 158 === Password Reset === 150 == Advanced configurations 151 152 === Password Reset 153 159 154 You need an authentication store enabled and configured correctly as a pre-requisite here. Additionally explicitly enable or unset the following option: 160 {{{ 161 #!cfg 155 {{{#!cfg 162 156 [account-manager] 163 157 ;reset_password = false 164 158 }}} 165 {{{ 166 #!cfg 159 {{{#!cfg 167 160 [components] 168 161 acct_mgr.notification.accountchangelistener = enabled … … 174 167 A detailed explanation of the [wiki:AccountManagerPlugin/Modules#Lostpasswordprocedure 'lost password' procedure] is available too. 175 168 176 '' 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.log177 178 === Persistent Sessions ===179 {{{ 180 #!cfg169 '''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. 170 171 === Persistent Sessions 172 173 {{{#!cfg 181 174 [account-manager] 182 175 persistent_sessions = true 183 176 }}} 184 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. 185 186 === Single Sign On === 177 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. 178 179 === Single Sign On 180 187 181 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. 188 182 … … 190 184 191 185 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: 192 {{{ 193 #!cfg 186 {{{#!cfg 194 187 [trac] 195 188 auth_cookie_path = /trac 196 189 }}} 190 197 191 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. 198 192 199 193 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. 200 194 201 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. 202 203 === Account Locking === 195 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. 196 197 === Account Locking 198 204 199 * new feature since acct_mgr-0.3 205 200 * available options (displayed with default values here): 206 201 207 {{{ 208 #!cfg 202 {{{#!cfg 209 203 [account-manager] 210 204 login_attempt_max_count = 0 … … 213 207 user_lock_time_progression = 1 214 208 }}} 215 {{{ 216 #!cfg 209 {{{#!cfg 217 210 [components] 218 211 acct_mgr.guard.accountguard = enabled 219 212 }}} 220 but this does '''nothing''' for backwards-compatibility, preventing surprises for unaware plugin-upgraders 221 222 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-expla ining in the way howit conditionally hides irrelevant options. So it's worth a look even for the console guru, who doesn't immediately understand these options.223 224 ==== Hard Lock-up ====225 {{{ 226 #!cfg213 but this does '''nothing''' for backwards-compatibility, preventing surprises for unaware plugin-upgraders. 214 215 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. 216 217 ==== Hard Lock-up 218 219 {{{#!cfg 227 220 [account-manager] 228 221 login_attempt_max_count = 5 … … 233 226 * no lock expiration, so release strictly '''requires administrator interaction''' 234 227 235 ==== Fixed login retry delay ====236 fixed delay time regardless of number of successive failed login attempts 237 238 {{{ 239 #!cfg228 ==== Fixed login retry delay 229 230 Fixed delay time regardless of number of successive failed login attempts 231 232 {{{#!cfg 240 233 [account-manager] 241 234 login_attempt_max_count = 3 … … 246 239 * release account lock 30 seconds after last failed login attempt 247 240 248 ==== Modestly progressing login retry delay ====249 {{{ 250 #!cfg241 ==== Modestly progressing login retry delay 242 243 {{{#!cfg 251 244 [account-manager] 252 245 login_attempt_max_count = 2 … … 279 272 ^![1]^ time after previous failed login attempt 280 273 281 ==== Aggressively progressing, but limited login retry delay ====282 {{{ 283 #!cfg274 ==== Aggressively progressing, but limited login retry delay 275 276 {{{#!cfg 284 277 [account-manager] 285 278 login_attempt_max_count = 4
