3.17. User authentication and session handling

Prev		Next

3.17.1. user_authenticate

This hooks gives modules a chance to handle the user authentication (for example to authenticate against an external source like an LDAP server).

Call time:

Just before Phorum runs its own user authentication.

Hook input:

An array containing the following fields:

type: either PHORUM_FORUM_SESSION or PHORUM_ADMIN_SESSION;
username: the username of the user to authenticate;
password: the password of the user to authenticate;
user_id: Always NULL on input. This field implements the authentication state.

Hook output:

The same array as the one that was used for the hook call argument, possibly with the user_id field updated. This field can be set to one of the following values by a module:

NULL: let Phorum handle the authentication
FALSE: the authentication credentials are rejected
1234: the numerical user_id of the authenticated user

Example code:

function phorum_mod_foo_user_authenticate($auth)
{
    // Only trust admin logins from IP addresses in 10.1.2.0/24.
    if ($auth["type"] == PHORUM_ADMIN_SESSION) {
        if (substr($_SERVER['REMOTE_ADDR'],0,7) != '10.1.2.') {
            $auth["user_id"] = FALSE;
            return $auth;
        }
    }

    // Let Phorum handle autentication for all users that
    // have a username starting with "bar" (not a really
    // useful feature, but it shows the use of the NULL
    // return value ;-).
    if (substr($auth["username"], 0, 3) == "bar") {
        $auth["user_id"] = NULL;
        return $auth;
    }

    // Authenticate other logins against an external source. Here
    // we call some made up function for checking the password,
    // which returns the user_id for the authenticated user.
    $user_id = some_func_that_checks_pw(
        $auth["username"],
        $auth["password"]
    );
    $auth["user_id"] = empty($user_id) ? FALSE : $user_id;
    return $auth;
}