Mercurial > p > roundup > code
comparison doc/admin_guide.txt @ 6436:1f2f7c0b8968
issue2550837 - New option for web auth (also http header passing)
Implement experimental support to allow tracker to use an alternate
authentication variable replacing ROUNDUP_USER. Also add -I option to
roundup-server to whitelist HTTP headers that should be passed through
to the tracker.
| author | John Rouillard <rouilj@ieee.org> |
|---|---|
| date | Mon, 14 Jun 2021 19:33:27 -0400 |
| parents | c63df349f319 |
| children | 8f1b91756457 |
comparison
equal
deleted
inserted
replaced
| 6435:ada96db8ec62 | 6436:1f2f7c0b8968 |
|---|---|
| 206 | 206 |
| 207 1. Through the web, users may be identified by either HTTP Basic | 207 1. Through the web, users may be identified by either HTTP Basic |
| 208 Authentication or cookie authentication. If you are running the web | 208 Authentication or cookie authentication. If you are running the web |
| 209 server (roundup-server) through another HTTP server (eg. apache or IIS) | 209 server (roundup-server) through another HTTP server (eg. apache or IIS) |
| 210 then that server may require HTTP Basic Authentication, and it will pass | 210 then that server may require HTTP Basic Authentication, and it will pass |
| 211 the ``REMOTE_USER`` variable through to Roundup. If this variable is not | 211 the ``REMOTE_USER`` variable (or variable defined using |
| 212 http_auth_header) through to Roundup. If this variable is not | |
| 212 present, then Roundup defaults to using its own cookie-based login | 213 present, then Roundup defaults to using its own cookie-based login |
| 213 mechanism. | 214 mechanism. |
| 214 2. In email messages handled by roundup-mailgw, users are identified by the | 215 2. In email messages handled by roundup-mailgw, users are identified by the |
| 215 From address in the message. | 216 From address in the message. |
| 216 | 217 |
| 226 will result in those users being registered with the tracker. | 227 will result in those users being registered with the tracker. |
| 227 | 228 |
| 228 More information about how to customise your tracker's security settings | 229 More information about how to customise your tracker's security settings |
| 229 may be found in the `customisation documentation`_. | 230 may be found in the `customisation documentation`_. |
| 230 | 231 |
| 232 Configuring Authentication Header/Variable | |
| 233 ------------------------------------------ | |
| 234 | |
| 235 The front end server running roundup can perform the user | |
| 236 authentication. It pass the authenticated username to the backend in a | |
| 237 variable. By default roundup looks for the ``REMOTE_USER`` variable | |
| 238 This can be changed by setting the parameter ``http_auth_header`` in the | |
| 239 ``[web]`` section of the tracker's ``config.ini`` file. If the value | |
| 240 is unset (the default) the REMOTE_USER variable is used. | |
| 241 | |
| 242 If you are running roundup using ``roundup-server`` behind a proxy | |
| 243 that authenticates the user you need to configure ``roundup-server`` to | |
| 244 pass the proper header to the tracker. By default ``roundup-server`` | |
| 245 looks for the ``REMOTE_USER`` header for the authenticated user. You | |
| 246 can copy an arbitrary header variable to the tracker using the ``-I`` | |
| 247 option to roundup-server (or the equivalent option in the | |
| 248 roundup-server config file). | |
| 249 | |
| 250 For example to use the ``uid_variable`` header, two configuration | |
| 251 changes are needed: First configure ``roundup-server`` to pass the | |
| 252 header to the tracker using:: | |
| 253 | |
| 254 roundup-server -I uid_variable .... | |
| 255 | |
| 256 note that the header is passed exactly as supplied by the upstream | |
| 257 server. It is **not** prefixed with ``HTTP_`` like other headers since | |
| 258 you are explicitly whitelisting the header. Multiple comma separated | |
| 259 headers can be passed to the ``-I`` option. These could be used in a | |
| 260 detector or other tracker extensions, but only one header can be used | |
| 261 by the tracker as an authentication header. | |
| 262 | |
| 263 To make the tracker honor the new variable changing the tracker | |
| 264 ``config.ini`` to read:: | |
| 265 | |
| 266 [web] | |
| 267 ... | |
| 268 http_auth_header = uid_variable | |
| 269 | |
| 270 At the time this is written, support is experimental. If you use it | |
| 271 you should notify the roundup maintainers using the roundup-users | |
| 272 mailing list. | |
| 231 | 273 |
| 232 Tasks | 274 Tasks |
| 233 ===== | 275 ===== |
| 234 | 276 |
| 235 Maintenance of Roundup can involve one of the following: | 277 Maintenance of Roundup can involve one of the following: |