[development] authentication hooks - PLEASE HELP

[Nedjo Rogers]

> - Which hook functions are called when (and not just from within the 
> Drupal
> code, but from what user action)? I thought that hook_auth() might be 
> called
> when the user logged in (that was a wild guess), but I can't get Drupal to
> call this function no matter what I do.

Yes, there is no clear documentation on where and how such hooks are 
invoked.  Including this information in the hook documentation would be a 
very useful addition.

To try to figure out when a particular hook is called, I tend to search 
through the core code.  The hooks are (generally) called through either 
module_invoke()  (for a particular module) or module_invoke_all() (for all 
modules) hooks.  I might try a search for

module_invoke_all('auth'

Which, in this case turns up nothing.  Then simply for

module_invoke($module, 'auth'

for which you'll get a hit in user.module.  If this too failed, try just the 
hook in single quotes

'auth'

Then, once you find the context, study the code and try to see under what 
condition the hook is called.  In this case (as someone noted) you'll find 
that the hook is called in user_authenticate, only if user_load() failed 
locally.