Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Plugin API/Filter Reference/authenticate

This page is marked as incomplete. You can help Codex by expanding it.


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.


(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
(string) (required) The user's username.
Default: None
(string) (optional) The user's password (plaintext - NOT encrypted).
Default: None


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


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.


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


Filter Hooks

Return to Plugin API/Filter Reference