wp_authenticate_application_password(): Авторизация через пароль приложения в WordPress

Функция wp_authenticate_application_password() используется для аутентификации пользователей WordPress с помощью паролей приложений. Это механизм, предназначенный для API-запросов, чтобы предоставить доступ к вашему сайту без использования основного пароля пользователя. Эта функция полезна для интеграций, когда приложения требуют доступа к API, но не должны использовать пароли пользователей напрямую.

wp_authenticate_application_password( WP_User|WP_Error|null $input_user, string $username, string $password ): WP_User|WP_Error|null

Описание

Функция позволяет аутентифицировать пользователя через пароль приложения. Если предоставленные данные корректны, функция возвращает объект пользователя (WP_User), иначе возвращает объект ошибки (WP_Error). Если функция получает на вход параметр null, и это не API-запрос, она возвращает null.

Параметры

• $input_user (WP_User|WP_Error|null, обязательный): Входной объект пользователя. Обычно это null. Если передан объект WP_User, функция просто вернёт его без изменений.
• $username (строка, обязательный): Имя пользователя или email для аутентификации.
• $password (строка, обязательный): Пароль приложения, который был создан в профиле пользователя.

Возвращаемое значение

• WP_User: Возвращается при успешной аутентификации.
• WP_Error: Возвращается при ошибке аутентификации.
• null: Возвращается, если параметр $input_user равен null, и запрос не является API-запросом.

Использование

Функция в основном используется системой WordPress для внутренней обработки API-запросов, но можно интегрировать её в свои собственные разработки для аутентификации через пароли приложений.

Пример использования 1: Основная проверка авторизации

В этом примере демонстрируется, как можно использовать функцию для аутентификации пользователя через пароль приложения.

// Аутентификация через пароль приложения
$username = 'example_user';
$app_password = 'ABCD-1234-EFGH-5678';

$authenticated_user = wp_authenticate_application_password( null, $username, $app_password );

if ( is_wp_error( $authenticated_user ) ) {
    echo 'Ошибка авторизации: ' . $authenticated_user->get_error_message();
} else {
    echo 'Успешная авторизация пользователя: ' . $authenticated_user->user_login;
}

В этом примере мы передаём имя пользователя и пароль приложения. Если аутентификация успешна, выводится сообщение об успешной авторизации с именем пользователя. В случае ошибки выводится сообщение об ошибке.

Пример использования 2: Аутентификация через REST API

Когда вы создаёте приложение, которое взаимодействует с REST API WordPress, пароли приложений могут использоваться для обеспечения безопасности запросов. В этом примере показано, как проверять пароль приложения при запросе к API.

// Проверка пароля приложения в REST API
add_action( 'rest_api_init', function () {
    register_rest_route( 'example/v1', '/secure-data/', array(
        'methods' => 'GET',
        'callback' => 'get_secure_data',
        'permission_callback' => function() {
            $username = isset( $_SERVER['PHP_AUTH_USER'] ) ? $_SERVER['PHP_AUTH_USER'] : '';
            $password = isset( $_SERVER['PHP_AUTH_PW'] ) ? $_SERVER['PHP_AUTH_PW'] : '';

            $user = wp_authenticate_application_password( null, $username, $password );

            return ! is_wp_error( $user );
        }
    ));
});

function get_secure_data() {
    return array( 'status' => 'Доступ разрешён!', 'data' => 'Секретные данные' );
}

В этом примере создаётся новый REST API маршрут, который требует авторизации через пароль приложения. Если пароль и имя пользователя верны, API возвращает данные, иначе доступ отклоняется.

Пример использования 3: Авторизация в пользовательских скриптах

Можно интегрировать проверку паролей приложений в пользовательские скрипты для автоматизации различных процессов. В этом примере демонстрируется, как использовать пароль приложения для выполнения административных задач через внешний скрипт.

// Проверка пользователя и выполнение задачи через пароль приложения
function perform_admin_task( $username, $app_password ) {
    $user = wp_authenticate_application_password( null, $username, $app_password );

    if ( is_wp_error( $user ) ) {
        return 'Ошибка: ' . $user->get_error_message();
    }

    // Выполняем административную задачу
    return 'Задача выполнена для пользователя: ' . $user->user_login;
}

// Используем функцию
$username = 'admin_user';
$app_password = 'XYZZ-1234-ABCD-5678';

$result = perform_admin_task( $username, $app_password );
echo $result;

Этот пример показывает, как можно использовать пароли приложений для выполнения задач от имени администратора. В случае успешной аутентификации задача будет выполнена, и пользователь получит подтверждение.

Пример использования 4: Обработка ошибок аутентификации

Когда необходимо обработать различные ошибки аутентификации, можно использовать объект WP_Error для вывода сообщений об ошибках. В этом примере показано, как это сделать.

// Обработка ошибок при аутентификации
$username = 'wrong_user';
$app_password = 'INVALID-PASSWORD';

$user = wp_authenticate_application_password( null, $username, $app_password );

if ( is_wp_error( $user ) ) {
    $error_code = $user->get_error_code();

    switch ( $error_code ) {
        case 'incorrect_password':
            echo 'Неверный пароль для пользователя.';
            break;
        case 'invalid_username':
            echo 'Пользователь с таким именем не найден.';
            break;
        default:
            echo 'Ошибка: ' . $user->get_error_message();
            break;
    }
} else {
    echo 'Успешная авторизация!';
}

В этом примере мы проверяем ошибки аутентификации и выводим соответствующие сообщения, чтобы пользователь мог лучше понимать, что пошло не так.

Пример использования 5: Внутренняя проверка на API-запрос

Когда аутентификация происходит через API, важно правильно обрабатывать запросы и сообщения об ошибках. В следующем примере мы показываем, как встроенная функция может использоваться для проверки API-запросов.

// Валидация запроса через API с паролем приложения
function validate_application_password( $input_user ) {
    if ( ! empty( $input_user ) ) {
        return $input_user;
    }

    if ( ! isset( $_SERVER['PHP_AUTH_USER'] ) ) {
        return $input_user;
    }

    $authenticated_user = wp_authenticate_application_password( null, $_SERVER['PHP_AUTH_USER'], $_SERVER['PHP_AUTH_PW'] );

    if ( $authenticated_user instanceof WP_User ) {
        return $authenticated_user;
    }

    return $input_user;
}

// Использование хука аутентификации
add_filter( 'authenticate', 'validate_application_password', 30, 1 );

Этот пример иллюстрирует, как настроить хук для использования паролей приложений в API-запросах.

Заключение

Функция wp_authenticate_application_password() — это мощный инструмент для аутентификации пользователей через API. Она предоставляет надёжный способ авторизации через пароли приложений и может быть полезна для интеграции с внешними сервисами, REST API и выполнения задач от имени пользователей.