WordPress Login Customization for External Authentication

Where … is handling the final true/false call returns in its traditional login concept?

The login process starts in the wp-login.php WordPress file around line 625:

$user = wp_signon('', $secure_cookie);

The wp_signon() function is from the wp-includes/user.php file.

/**
 * Authenticate user with remember capability.
 *
 * The credentials is an array that has 'user_login', 'user_password', and
 * 'remember' indices. If the credentials is not given, then the log in form
 * will be assumed and used if set.
 *
 * The various authentication cookies will be set by this function and will be
 * set for a longer period depending on if the 'remember' credential is set to
 * true.
 *
 * @since 2.5.0
 *
 * @param array $credentials Optional. User info in order to sign on.
 * @param bool $secure_cookie Optional. Whether to use secure cookie.
 * @return object Either WP_Error on failure, or WP_User on success.
 */
function wp_signon( $credentials="", $secure_cookie="" ) {
    if ( empty($credentials) ) {
        if ( ! empty($_POST['log']) )
            $credentials['user_login'] = $_POST['log'];
        if ( ! empty($_POST['pwd']) )
            $credentials['user_password'] = $_POST['pwd'];
        if ( ! empty($_POST['rememberme']) )
            $credentials['remember'] = $_POST['rememberme'];
    }

    if ( !empty($credentials['remember']) )
        $credentials['remember'] = true;
    else
        $credentials['remember'] = false;

    // TODO do we deprecate the wp_authentication action?
    do_action_ref_array('wp_authenticate', array(&$credentials['user_login'], &$credentials['user_password']));

    if ( '' === $secure_cookie )
        $secure_cookie = is_ssl();

    $secure_cookie = apply_filters('secure_signon_cookie', $secure_cookie, $credentials);

    global $auth_secure_cookie; // XXX ugly hack to pass this to wp_authenticate_cookie
    $auth_secure_cookie = $secure_cookie;

    add_filter('authenticate', 'wp_authenticate_cookie', 30, 3);

    $user = wp_authenticate($credentials['user_login'], $credentials['user_password']);

    if ( is_wp_error($user) ) {
        if ( $user->get_error_codes() == array('empty_username', 'empty_password') ) {
            $user = new WP_Error('', '');
        }

        return $user;
    }

    wp_set_auth_cookie($user->ID, $credentials['remember'], $secure_cookie);
    do_action('wp_login', $user->user_login, $user);
    return $user;
}

I’m not an expert on this topic, but it looks like you have two choices.

1) Rewrite the wp_authenticate() function located in the wp-includes/pluggable.php.

All the functions in wp-includes/pluggable.php, check to see if the function already exists before creating the function, so you can add the rewritten function in a theme or a plugin and it will replace the default wp_authenticate() function.

2) Add your layer to ‘wp_login’ action hook located near the end of the function.

The ‘wp_login’ action occurs after WordPress is done with all authentication. Use it like this.

add_action( 'wp_login', 'my_external_authentication', 10, 2 );
/**
 * @return object Either WP_Error on failure, or WP_User on success.
 */
function my_external_authentication( $user_login, $user ) {
    // Add external authentication here.
}