分析 WordPress `rest_authentication_errors` 钩子源码：如何自定义 REST API 的认证逻辑。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

各位观众，欢迎来到今天的WordPress REST API认证魔改讲座！我是今天的讲师，一个和bug战斗多年的老码农。今天咱们不搞虚的，直接上干货，聊聊如何通过rest_authentication_errors这个神奇的钩子，把WordPress REST API的认证逻辑玩出花来。

一、WordPress REST API认证基础：先摸清家底

在开始魔改之前，咱们得先搞清楚WordPress默认的REST API认证机制是怎么回事。简单来说，它主要依赖以下几种方式：

Cookies认证： 这是最常见的，当你登录WordPress后台后，浏览器会保存一个cookie，每次发送REST API请求时，WordPress会检查这个cookie，看你是不是已经登录了。这种方式只适用于同一个域名下的请求。
Nonce认证： 这种认证方式通常用于前端发起的请求，例如使用wp_localize_script()函数传递的nonce值。Nonce是一个一次性的令牌，用于验证请求的合法性。
Basic Auth： 这种方式需要在请求头中包含Authorization: Basic <base64编码的用户名:密码>。这种方式安全性较差，通常只用于测试环境或HTTPS连接。
OAuth 1.0a： 这种方式是一种更安全的认证方式，需要注册OAuth客户端，获取consumer key和secret，然后使用这些凭证来签名请求。WordPress自身没有内置OAuth 1.0a服务器，需要安装插件来实现。
JWT (JSON Web Tokens)： JWT是一种基于令牌的认证方式，服务器验证用户的凭据后，会颁发一个JWT，客户端在后续的请求中携带这个JWT，服务器验证JWT的有效性即可。同样，WordPress自身没有内置JWT支持，需要安装插件来实现。

这些默认的认证方式，在很多情况下都能满足需求。但是，总有些时候，我们需要一些更定制化的认证逻辑，比如：

自定义用户表： 假设你的用户数据不在WordPress的wp_users表中，而是在你自己的数据库表中。
第三方认证： 你想使用微信、QQ、支付宝等第三方账号来登录WordPress。
API Key认证： 你想为外部应用提供API接口，使用API Key来验证请求。
双因素认证： 你想增加一层安全保障，要求用户在登录时输入验证码。

这时候，rest_authentication_errors钩子就派上用场了。

二、rest_authentication_errors钩子：认证错误的拦截器

rest_authentication_errors钩子会在REST API认证失败时被触发。它的作用就像一个认证错误的拦截器，允许你检查当前的认证错误，并决定是否阻止请求，或者提供自定义的认证方案。

这个钩子接收一个WP_Error对象作为参数，这个对象包含了认证错误的信息。你可以通过$error->get_error_code()和$error->get_error_message()方法来获取错误代码和错误信息。

三、实战演练：自定义API Key认证

接下来，咱们来做一个实战演练，实现一个自定义的API Key认证。假设我们有一个API Key列表，存储在数据库中，我们要验证每个请求是否携带了有效的API Key。

注册钩子：

首先，在你的插件或主题的functions.php文件中，注册rest_authentication_errors钩子：

add_filter( 'rest_authentication_errors', 'my_custom_api_key_authentication' );

实现认证逻辑：

然后，实现my_custom_api_key_authentication()函数：

/**
 * 自定义API Key认证
 *
 * @param WP_Error|null $errors 认证错误对象，如果认证成功，则为null
 * @return WP_Error|null
 */
function my_custom_api_key_authentication( $errors ) {
    // 如果已经有错误，直接返回
    if ( ! empty( $errors ) ) {
        return $errors;
    }

    // 获取API Key
    $api_key = isset( $_SERVER['HTTP_X_API_KEY'] ) ? $_SERVER['HTTP_X_API_KEY'] : '';

    // 验证API Key
    if ( ! my_validate_api_key( $api_key ) ) {
        // 创建一个新的错误对象
        $errors = new WP_Error(
            'rest_api_key_invalid',
            __( 'Invalid API Key', 'my-plugin' ),
            array( 'status' => 401 )
        );
    }

    return $errors;
}

验证API Key的函数：

接下来，实现my_validate_api_key()函数，这个函数负责从数据库中查询API Key，并验证其有效性：

/**
 * 验证API Key
 *
 * @param string $api_key API Key
 * @return bool
 */
function my_validate_api_key( $api_key ) {
    global $wpdb;

    // 从数据库中查询API Key
    $table_name = $wpdb->prefix . 'api_keys';
    $sql = $wpdb->prepare(
        "SELECT * FROM {$table_name} WHERE api_key = %s AND status = %d",
        $api_key,
        1 // 1表示启用状态
    );
    $result = $wpdb->get_row( $sql );

    // 如果查询结果不为空，则API Key有效
    return ! empty( $result );
}

创建API Key表：

最后，我们需要创建一个wp_api_keys表来存储API Key。可以在插件激活时创建这个表：

/**
 * 插件激活时创建API Key表
 */
function my_plugin_activate() {
    global $wpdb;

    $table_name = $wpdb->prefix . 'api_keys';
    $charset_collate = $wpdb->get_charset_collate();

    $sql = "CREATE TABLE IF NOT EXISTS {$table_name} (
        id mediumint(9) NOT NULL AUTO_INCREMENT,
        api_key varchar(255) NOT NULL,
        description text,
        status tinyint(1) NOT NULL DEFAULT 1,
        created_at datetime DEFAULT CURRENT_TIMESTAMP,
        PRIMARY KEY  (id)
    ) {$charset_collate};";

    require_once( ABSPATH . 'wp-admin/includes/upgrade.php' );
    dbDelta( $sql );
}
register_activation_hook( __FILE__, 'my_plugin_activate' );

代码解释：

add_filter( 'rest_authentication_errors', 'my_custom_api_key_authentication' );：这行代码将my_custom_api_key_authentication函数注册为rest_authentication_errors钩子的回调函数。
my_custom_api_key_authentication( $errors )：这个函数接收一个WP_Error对象作为参数。如果已经有认证错误，则直接返回这个对象。否则，从请求头中获取API Key，并调用my_validate_api_key()函数来验证API Key的有效性。如果API Key无效，则创建一个新的WP_Error对象，并返回。
my_validate_api_key( $api_key )：这个函数从数据库中查询API Key，并验证其有效性。
my_plugin_activate()：这个函数在插件激活时创建wp_api_keys表。

使用方法：

将以上代码保存为一个插件文件，例如my-api-key-auth.php。
激活插件。
在wp_api_keys表中添加一些API Key。
发送REST API请求时，在请求头中包含X-API-KEY字段，值为你的API Key。例如：

X-API-KEY: your_api_key

如果API Key有效，则请求会正常执行。否则，会返回一个401错误，提示"Invalid API Key"。

四、进阶技巧：更灵活的认证控制

除了简单的API Key认证，rest_authentication_errors钩子还可以实现更复杂的认证逻辑。

根据路由选择认证方式：

你可以根据请求的路由，选择不同的认证方式。例如，对于某些公共API，可以允许匿名访问，而对于其他API，则需要API Key认证。

function my_custom_authentication( $errors ) {
    $route = isset( $_SERVER['REQUEST_URI'] ) ? $_SERVER['REQUEST_URI'] : '';

    // 对于/public/api路由，允许匿名访问
    if ( strpos( $route, '/public/api' ) !== false ) {
        return $errors; // 返回null表示允许访问
    }

    // 其他路由需要API Key认证
    // ... (API Key认证逻辑)
}

链式认证：

你可以实现链式认证，即依次尝试多种认证方式，直到其中一种认证成功为止。

function my_custom_authentication( $errors ) {
    // 尝试API Key认证
    $errors = my_api_key_authentication( $errors );
    if ( empty( $errors ) ) {
        return $errors; // API Key认证成功
    }

    // 尝试OAuth 2.0认证
    $errors = my_oauth2_authentication( $errors );
    if ( empty( $errors ) ) {
        return $errors; // OAuth 2.0认证成功
    }

    // 所有认证方式都失败，返回错误
    return $errors;
}

自定义错误信息：

你可以自定义认证失败时的错误信息，使其更友好、更易于理解。

function my_custom_authentication( $errors ) {
    // ... (认证逻辑)

    if ( /* 认证失败 */ ) {
        $errors = new WP_Error(
            'my_custom_auth_failed',
            __( 'Authentication failed: Please check your credentials.', 'my-plugin' ),
            array( 'status' => 401 )
        );
    }

    return $errors;
}

五、注意事项：安全第一

在自定义REST API认证逻辑时，一定要注意安全问题。

HTTPS： 务必使用HTTPS协议，防止敏感信息被窃取。
输入验证： 对所有输入进行验证，防止SQL注入、XSS等攻击。
API Key保护： 不要将API Key存储在客户端代码中，防止泄露。
速率限制： 对API请求进行速率限制，防止恶意攻击。
定期审查： 定期审查你的认证逻辑，确保其安全性。

六、总结：玩转rest_authentication_errors

rest_authentication_errors钩子是WordPress REST API认证魔改的利器。通过它可以实现各种自定义的认证逻辑，满足不同的需求。但是，在魔改的同时，一定要注意安全问题，确保你的API接口安全可靠。

希望今天的讲座能帮助你更好地理解和使用rest_authentication_errors钩子。记住，代码的世界是无限的，只要你有想法，就能创造出无限的可能！

附录：常用错误代码

错误代码	描述	HTTP状态码
`rest_authentication_required`	需要认证，但未提供任何认证信息	401
`rest_cookie_invalid_nonce`	Cookie认证失败，Nonce无效	403
`rest_cannot_edit`	没有编辑权限	401
`rest_forbidden`	禁止访问，通常是权限不足	403
`rest_user_invalid_password`	用户名或密码错误	401
`rest_api_key_invalid`	自定义错误代码，API Key无效	401

好了，今天的讲座就到这里。感谢大家的观看！如果有什么问题，欢迎在评论区留言。

发表回复 取消回复

发表回复取消回复