do_action_ref_array( 'wp_authenticate', string $user_login, string $user_password )

Fires before the user is authenticated.

Description Description

The variables passed to the callbacks are passed by reference, and can be modified by callback functions.

Top ↑

Parameters Parameters


(string) Username (passed by reference).


(string) User password (passed by reference).

Top ↑

More Information More Information

This action is located inside of wp_signon(). In contrast to the wp_login action, it is executed before the WordPress authentication process.

This action hook is not to be confused with the wp_authenticate() pluggable function.

Top ↑

Source Source

File: wp-includes/user.php

View on Trac

Top ↑

Changelog Changelog

Version Description
1.5.1 Introduced.

Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 1 content
    Contributed by ChadCloman

    To actually modify the values, it’s necessary to use ampersands in the callback function declaration:

    function wpdocs_my_function( &$user_login, &$user_password ) {
    	$user_login = 'new_username';
    	$user_password = 'new_password';
    add_action( 'wp_authenticate', 'wpdocs_my_function', 10, 2 );
  2. Skip to note 2 content
    Contributed by stevenlinx

    Example migrated from Codex:

    You can use wp_authenticate action hook to implement a custom login mechanism before you involve WordPress.

    add_action( 'wp_authenticate' , 'check_custom_authentication' );
    function check_custom_authentication ( $username ) {
        global $wpdb;
        if ( ! username_exists( $username ) ) {
        $userinfo = get_user_by( 'login', $username );
        $property = $wpdb->prefix . 'capabilities';
        $caps = $userinfo->$property;
        foreach ( $caps as $role ) {
            if ( 'special_authenticator' == $role ) {
                wpExternalLoginProcess( $username, $_POST['pwd'] );
  3. Skip to note 3 content
    Contributed by stevenlinx

    Example migrated from Codex:

    You can also use email to authenticate users in WordPress.

    // username is passed in by reference 
    function wp_authenticate_by_email( &$username ) {
        $user = get_user_by( 'email', $username );
        if ( ! $user ) {
            $username = $user->user_login;
    add_action( 'wp_authenticate', 'wp_authenticate_by_email' );

You must log in before being able to contribute a note or feedback.