authenticate │ filter-hook │ WP 2.8.0

Allows you to perform additional checks on a user's authentication credentials (login/password) before the user is authenticated.

The filter fires whenever a user logs in to the site.

This filter performs WordPress's basic login/password check.

Usage

add_filter( 'authenticate', 'wp_kama_authenticate_filter', 10, 3 );

/**
 * Function for `authenticate` filter-hook.
 * 
 * @param null|WP_User|WP_Error $user     WP_User if the user is authenticated. WP_Error or null otherwise.
 * @param string                $username Username or email address.
 * @param string                $password User password.
 *
 * @return null|WP_User|WP_Error
 */
function wp_kama_authenticate_filter( $user, $username, $password ){

	// filter...
	return $user;
}

$user(null/WP_User/WP_Error)

A WP_User object if the user passed the check, a WP_Error object, or null.

The callback can return:

• WP_User — the check passed, and subsequent checks may proceed.
• null — no authentication check has occurred yet.
• WP_Error — a check occurred, but the credentials failed it.

$username(string)

Username or email address. Email addresses are supported since WP 4.5.0; before that, only a username could be specified.

$password(string)

Password in unencrypted form.

Examples

#1 Cookie authentication

After you enter a username and password and are authenticated, a temporary hash of the password is stored in a cookie, functioning somewhat like a session.

Authentication from this cookie hash also occurs on this hook through wp_authenticate_cookie().

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

#2 Application Password authentication

After Application Passwords were added, authentication with an Application Password also began to occur on this hook. It is handled by wp_authenticate_application_password().

add_filter( 'authenticate', 'wp_authenticate_application_password', 20, 3 );

#3 Basic WordPress authentication check (username and password)

Three functions are attached to the authenticate hook for the basic check:

• wp_authenticate_username_password()
• wp_authenticate_email_password()
• wp_authenticate_spam_check()

From /wp-includes/default-filters.php.

// Default authentication filters.
add_filter( 'authenticate', 'wp_authenticate_username_password',  20, 3 );
add_filter( 'authenticate', 'wp_authenticate_email_password',     20, 3 );
add_filter( 'authenticate', 'wp_authenticate_spam_check',         99    );