| How Auth Works |
| ============== |
| Christian Reis <kiko@async.com.br> |
| |
| Overview |
| -------- |
| |
| Authentication in Bugzilla is handled by a collection of modules that live in |
| the Bugzilla::Auth package. These modules are organized hierarchically based |
| upon their responsibility. |
| |
| The authentication scheme is divided in two tasks: Login and Verify. Login |
| involves gathering credentials from a user, while Verify validates them |
| against an authentication service. |
| |
| The Bugzilla parameters user_info_class and user_verify_class contain a |
| list of Login and Verify modules, respectively. |
| |
| Task: Login |
| ----------- |
| |
| This task obtains user credentials based on a request. Examples of requests |
| include CGI access from the Bugzilla web interface, email submissions and |
| credentials supplied by standalone scripts. |
| |
| Each type of Bugzilla front-end should have its own package. For instance, |
| access via the Bugzilla web pages should go through Bugzilla::Auth::WWW. |
| These packages would contain modules of their own to perform whatever extra |
| functions are needed, like the CGI and Cookie modules in the case of WWW. |
| |
| Task: Verify |
| ------------ |
| |
| This task validates user credentials against a user authentication service. |
| |
| The default service in Bugzilla has been the database, which stores the |
| login_name and cryptpasswd fields in the profiles table. An alternative means |
| of validation, LDAP, is already supported, and other contributions would be |
| appreciated. |
| |
| The module layout is similar to the Login package, but there is no need for a |
| sub-level as there is with Login request types. |
| |
| Params |
| ------ |
| |
| There are two params that define behaviour for each authentication task. Each |
| of them defines a comma-separated list of modules to be tried in order. |
| |
| - user_info_class determines the module(s) used to obtain user |
| credentials. This param is specific to the requests from Bugzilla web |
| pages, so all of the listed modules live under |
| Bugzilla::Auth::Login::WWW |
| |
| - user_verify_class determines the module(s) used to verify credentials. |
| This param is general and concerns the whole Bugzilla instance, since |
| the same back end should be used regardless of what front end is used. |
| |
| Responsibilities |
| ---------------- |
| |
| Bugzilla::Auth |
| |
| This module is responsible for abstracting away as much as possible the |
| login and logout tasks in Bugzilla. |
| |
| It offers login() and logout() methods that are proxied to the selected |
| login and verify packages. |
| |
| Bugzilla::Auth::Login |
| |
| This is a container to hold the various modules for each request type. |
| |
| Bugzilla::Auth::Login::WWW |
| |
| This module is responsible for abstracting away details of which web-based |
| login modules exist and are in use. It offers login() and logout() methods |
| that proxy through to whatever specific modules |
| |
| Bugzilla::Auth::Verify |
| |
| This module is responsible for abstracting away details of which |
| credential verification modules exist, and should proxy calls through to |
| them. There is a method that is particularly important, and which should |
| be proxied through to the specific: |
| |
| can_edit($type) |
| |
| This method takes an argument that specifies what sort of change |
| is being requested; the specific module should return 1 or 0 based |
| on the fact that it implements or not the required change. |
| |
| Current values for $type are "new" for new accounts, and "userid", |
| "login_name", "realname" for their respective fields. |
| |
| Specific Login Modules |
| ---------------------- |
| |
| WWW |
| |
| The main authentication frontend; regular pages (CGIs) should use only |
| this module. It offers a convenient frontend to the main functionality |
| that CGIs need, using form parameters and cookies. |
| |
| - Cookie |
| |
| Implements part of the backend code that deals with browser |
| cookies. It's actually tied in to DB.pm, so Cookie logins that use |
| LDAP won't work at all. |
| |
| LDAP |
| |
| The other authentication module is LDAP-based; it is *only* used for |
| password authentication and not for any other login-related task (it |
| actually relies on the database to handle the profile information). |
| |
| Legacy |
| ------ |
| |
| Bugzilla.pm |
| |
| There is glue code that currently lives in the top-level module |
| Bugzilla.pm; this module handles backwards-compatibility data that is used |
| in a number of CGIs. This data has been slowly removed from the Bugzilla |
| pages and eventually should go away completely, at which point Bugzilla.pm |
| will be just a wrapper to conveniently offer template, cgi, dbh and user |
| variables. |
| |
| This module is meant to be used only by Bugzilla pages, and in the case of |
| a reorganization which moves CGI-specific code to a subdirectory, |
| Bugzilla.pm should go with it. |
| |