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

Filters whether a set of user login credentials are valid.

Contents

Description

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

Top ↑

Parameters

$user null|WP_User|WP_Error
WP_User if the user is authenticated.
WP_Error or null otherwise.
$username string
Username or email address.
$password string
User password.

Top ↑

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

Top ↑

Source

File: wp-includes/pluggable.php. View all references 

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

View on Trac View on GitHub

Top ↑

Top ↑

Changelog

Changelog
Version Description
4.5.0 $username now accepts an email address.
2.8.0 Introduced.

Top ↑

User Contributed Notes

  1. Skip to note 1 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note
    Contributed by Rahul Prajapati —

    ==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 2 content
    You must log in to vote on the helpfulness of this noteVote results for this note: -2You must log in to vote on the helpfulness of this note
    Contributed by Dragi Postolovski — 
    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 3 content
    You must log in to vote on the helpfulness of this noteVote results for this note: -3You must log in to vote on the helpfulness of this note
    Contributed by pronl —

    … 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.