WordPress.org

Description

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

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

Parameters

$user

(null or WP_User or WP_Error) (required) null indicates no process has authenticated the user yet. A WP_Error object indicates another process has failed the authentication. A WP_User object indicates another process has authenticated the user.

Default: None

$username

(string) (required) The user's username.

Default: None

$password

(string) (optional) The user's password (plaintext - NOT encrypted).

Default: None

Returns

Your hook callback should return either a WP_User object if authenticating the user or, if generating an error, a WP_Error object.

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.

Notes

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 File

The authenticate hook is located in /wp-includes/pluggable.php within wp_authenticate()

Related

Filter Hooks

• authenticate
• wp_authenticate_user

Return to Plugin API/Filter Reference