WordPress at a glance

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.

  • Since 4.5.0 $username now accepts an email address.

This is a pluggable function, and it can be replaced from plugin. It means that this function is defined (works) only after all plugins are connected (included), but before this moment the function has not yet been defined... Therefore, you cannot call this and all functions depended on this function directly from a plugin code. It must be called via hook plugins_loaded or later, for example on hook init.

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

Is the basis for: wp_signon()

No Hooks.

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

#2.2 Authorize user by login only

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

Code of wp_authenticate: wp-includes/pluggable.php VER 5.0.1

<?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 ( $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.' ) );
	}

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

	if (is_wp_error($user) && !in_array($user->get_error_code(), $ignore_codes) ) {
		/**
		 * 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.
		 *
		 * @param string $username Username or email address.
		 */
		do_action( 'wp_login_failed', $username );
	}

	return $user;
}

Related Functions

From tag: authenticate (authentication login)

More from category: Login/Logout

No comments
    Hello, !     Log In . Register