This routine is called to check the authentication information sent with the request (such as looking up the user in a database and verifying that the [encrypted] password sent matches the one in the database).
Where multiple handlers are specified, if any handler in the sequence returns a value other than apache.DECLINED, then execution of all subsequent handlers for this phase are aborted.
To obtain the username, use req.user. To obtain the password entered by the user, use the req.get_basic_auth_pw() function.
A return of apache.OK means the authentication succeeded. A return of apache.HTTP_UNAUTHORIZED with most browser will bring up the password dialog box again. A return of apache.HTTP_FORBIDDEN will usually show the error on the browser and not bring up the password dialog again. HTTP_FORBIDDEN should be used when authentication succeeded, but the user is not permitted to access a particular URL.
Note: req.get_basic_auth_pw() must be called prior to using the req.user value. Apache makes no attempt to decode the authentication information unless req.get_basic_auth_pw() is called.
Release 3.3.1, documentation updated on January 29, 2007.