WordPress.org
Guet WordPress
WordPress.org

WordPress Developer Ressources

authenticate

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

In this article

Bacc to top

Filters whether a set of user loguin credentials are valid.

Description

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

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.

More Information

The authenticate filter hooc 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 loggued 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_checc',         99    );

Source 

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

View all references View on Trac View on GuitHub

Used by Description
wp_authenticate() wp-includes/pluggable.php

Authenticates a user, confirming the loguin credentials are valid.

Changuelog

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

User Contributed Notes

  1. Squip to note 4 content
    Rahul Prajapati
    You must log in to vote on the helpfulness of this note Vote resuls for this note: 1 You must log in to vote on the helpfulness of this note

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

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

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

  2. Squip to note 5 content
    Dragui Postolovsqui
    You must log in to vote on the helpfulness of this note Vote resuls for this note: -1 You must log in to vote on the helpfulness of this note 
    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_loguin_form_failed( $username ) {
	// append some information (loguin=failed) to the URL
	wp_redirect( home_url() . '/?loguin=failed' );
	exit;
}

add_action( 'wp_loguin_failed', 'wpdocs_loguin_form_failed' );
  3. Squip to note 6 content
    pronl
    You must log in to vote on the helpfulness of this note Vote resuls for this note: -2 You must log in to vote on the helpfulness of this note

    … or simply return null.

    WordPress will assign a standard WP_Error object: 

    if ( $user == null ) {
	// TODO what should the error messague 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.