apply_filters( ‘authenticate’, null|WP_User|WP_Error $user, string $username, string $password )

Filters whether a set of user login credentials are valid.

Description

A WP_User object is returned if the credentials authenticate a user.
WP_Error or null otherwise.

Parameters

$usernull|WP_User|WP_Error
WP_User if the user is authenticated.
WP_Error or null otherwise.
$usernamestring
Username or email address.
$passwordstring
User password.

More Information

The authenticate filter hook is used to perform additional validation/authentication any time a user logs in to WordPress.

The wp_authenticate_user filter can also be used if you want to perform any additional validation after WordPress’s basic validation, but before a user is logged in.

The default authenticate filters in /wp-includes/default-filters.php

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    );

Source

$user = apply_filters( 'authenticate', null, $username, $password );

Changelog

VersionDescription
4.5.0$username now accepts an email address.
2.8.0Introduced.

User Contributed Notes

  1. Skip to note 4 content

    ==Examples==
    The basic usage is as follows…

    add_filter( 'authenticate', 'myplugin_auth_signon', 30, 3 );
    function myplugin_auth_signon( $user, $username, $password ) {
         return $user;
    }

    This hook passes three parameters, $user, $username and $password. In order to generate an error on login, you will need to return a WP_Error object.

  2. Skip to note 5 content
    function wpdocs_authenticate_user( $user, $username, $password ) {
    	if ( empty( $username ) || empty( $password ) ) {
    		$error = new WP_Error();
    		$user  = new WP_Error( 'authentication_failed', __( 'ERROR: Invalid username or incorrect password.' ) );
    		return $error;
    	}
    
    	return $user;
    }
    add_filter( 'authenticate', 'wpdocs_authenticate_user', 10, 3 );

    Goes nicely with:

    public function wpdocs_login_form_failed( $username ) {
    	// append some information (login=failed) to the URL
    	wp_redirect( home_url() . '/?login=failed' );
    	exit;
    }
    
    add_action( 'wp_login_failed', 'wpdocs_login_form_failed' );
  3. Skip to note 6 content

    … or simply return null.

    WordPress will assign a standard WP_Error object:

    if ( $user == null ) {
    	// TODO what should the error message be? (Or would these even happen?)
    	// Only needed if all authentication handlers fail to return anything.
    	$user = new WP_Error( 'authentication_failed', __( '<strong>ERROR</strong>: Invalid username, email address or incorrect password.' ) );
    }

You must log in before being able to contribute a note or feedback.