wp_authenticate() │ WP 2.5.0

Checks the authorization data of the registered user (login and password) and authorizes it if the check was passed.

This function does nothing itself but passes the username and password to the filter authenticate. Through this filter, the transmitted username and password are checked, and the user is authorized.

Pluggable function — this function can be replaced from a plugin. It means that this function is defined (works) only after all plugins are loaded (included), but before this moment this function has not defined. Therefore, you cannot call this and all functions depended on this function directly from a plugin code. They need to be called on plugins_loaded hook or later, for example on init hook.

Function replacement (override) — in must-use or regular plugin you can create a function with the same name, then it will replace this function.

Uses: wp_authenticate_username_password(), wp_authenticate_email_password()

Used By: wp_signon()

Hooks from the function

authenticate

wp_login_failed

Return

WP_User|WP_Error. WP_User object if the credentials are valid, otherwise WP_Error.

Usage

wp_authenticate( $username, $password );

$username(string) (required): User's username or email address.
$password(string) (required): User's password.

Examples

#1 Authorize user

Suppose we have a username and password and we need to authorize (login) a user with this data. We can do it like this:

$username = 'truegamer';
$password = 'live_is_a_game';

// Authorize
$auth = wp_authenticate( $username, $password );

// Error checking
if ( is_wp_error( $auth ) ) {
	$error_string = $auth->get_error_message();
	echo '<div id="message" class="error"><p>' . $error_string . '</p></div>';
}
else {
	echo 'Authorization was successful!';
}

#2 Authorize user by email only

This example shows how to enable user authorization in WordPress only by email.

Since WP 4.5 Wordpress automatically authorizes the user by email or login, i.e. you can pass email into the login field (username parameter). Two functions are responsible for such authorization. Both are hanging on the hook authenticate in the file /wp-includes/default-filters.php.

add_filter( 'authenticate', 'wp_authenticate_username_password',  20, 3 );
add_filter( 'authenticate', 'wp_authenticate_email_password',     20, 3 );

Thus, to disable authorization by login, but leave authorization by mail, you just need to disable the filter associated with the login:

remove_filter( 'authenticate', 'wp_authenticate_username_password',  20, 3 );

#3 Authorize user by login only (disable auth by email)

To leave authentication as it was before WP 4.5. - only by login, you need to remove new filter associated with email:

remove_filter( 'authenticate', 'wp_authenticate_email_password',     20, 3 );

Changelog

Since 2.5.0	Introduced.
Since 4.5.0	`$username` now accepts an email address.

`wp_authenticate() wp authenticate` code ^{WP 6.5.2}

wp-includes/pluggable.php

function wp_authenticate( $username, $password ) {
	$username = sanitize_user( $username );
	$password = trim( $password );

	/**
	 * Filters whether a set of user login credentials are valid.
	 *
	 * A WP_User object is returned if the credentials authenticate a user.
	 * WP_Error or null otherwise.
	 *
	 * @since 2.8.0
	 * @since 4.5.0 `$username` now accepts an email address.
	 *
	 * @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.
	 */
	$user = apply_filters( 'authenticate', null, $username, $password );

	if ( null == $user ) {
		/*
		 * 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.' ) );
	}

	$ignore_codes = array( 'empty_username', 'empty_password' );

	if ( is_wp_error( $user ) && ! in_array( $user->get_error_code(), $ignore_codes, true ) ) {
		$error = $user;

		/**
		 * Fires after a user login has failed.
		 *
		 * @since 2.5.0
		 * @since 4.5.0 The value of `$username` can now be an email address.
		 * @since 5.4.0 The `$error` parameter was added.
		 *
		 * @param string   $username Username or email address.
		 * @param WP_Error $error    A WP_Error object with the authentication failure details.
		 */
		do_action( 'wp_login_failed', $username, $error );
	}

	return $user;
}