How Auth Works ============== Christian Reis 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. $::COOKIE There are still instances of use of $::COOKIE to obtain Logincookie information; these should be removed as well.