do_action_ref_array( ‘wp_authenticate’, string $user_login, string $user_password )

Fires before the user is authenticated.

Description

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

Parameters

$user_loginstring
Username (passed by reference).
$user_passwordstring
User password (passed by reference).

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.

Source

do_action_ref_array( 'wp_authenticate', array( &$credentials['user_login'], &$credentials['user_password'] ) );

Changelog

VersionDescription
1.5.1Introduced.

User Contributed Notes

  1. Skip to note 4 content

    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 5 content

    Example migrated from Codex:

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

    <?php
    add_action( 'wp_authenticate' , 'check_custom_authentication' );
    
    function check_custom_authentication ( $username ) {
        global $wpdb;
    
        if ( ! username_exists( $username ) ) {
            return;
        }
    
        $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 6 content

    Example migrated from Codex:

    You can also use email to authenticate users in WordPress.

    <?php
    // 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.