rest_cookie_check_errors()
云策文档标注
概述
rest_cookie_check_errors() 是 WordPress REST API 中用于检查基于 cookie 身份验证错误的函数。它验证请求中的 nonce 以防止 CSRF 攻击，并处理身份验证状态。
关键要点
- 函数检查 cookie 身份验证错误，确保登录用户请求的安全性。
- 参数 $result 接受 WP_Error 或其他值，用于处理其他身份验证程序的结果。
- 返回 WP_Error（如果 cookie 无效）、$result 或 true。
- 核心逻辑包括检查 $wp_rest_auth_cookie 全局变量、获取 nonce 并验证其有效性。
- 验证失败时返回 WP_Error 并添加过滤器以阻止缓存头。
- 验证成功时发送刷新的 nonce 到响应头。
代码示例
function rest_cookie_check_errors( $result ) {
if ( ! empty( $result ) ) {
return $result;
}
global $wp_rest_auth_cookie;
if ( true !== $wp_rest_auth_cookie && is_user_logged_in() ) {
return $result;
}
$nonce = null;
if ( isset( $_REQUEST['_wpnonce'] ) ) {
$nonce = $_REQUEST['_wpnonce'];
} elseif ( isset( $_SERVER['HTTP_X_WP_NONCE'] ) ) {
$nonce = $_SERVER['HTTP_X_WP_NONCE'];
}
if ( null === $nonce ) {
wp_set_current_user( 0 );
return true;
}
$result = wp_verify_nonce( $nonce, 'wp_rest' );
if ( ! $result ) {
add_filter( 'rest_send_nocache_headers', '__return_true', 20 );
return new WP_Error( 'rest_cookie_invalid_nonce', __( 'Cookie check failed' ), array( 'status' => 403 ) );
}
rest_get_server()->send_header( 'X-WP-Nonce', wp_create_nonce( 'wp_rest' ) );
return true;
}注意事项
- 函数依赖于全局变量 $wp_rest_auth_cookie 和 is_user_logged_in() 来判断是否使用 cookie 身份验证。
- nonce 可从 $_REQUEST['_wpnonce'] 或 $_SERVER['HTTP_X_WP_NONCE'] 获取，优先检查前者。
- 验证失败时返回 403 状态码的 WP_Error，并触发 rest_send_nocache_headers 过滤器。
- 成功验证后，通过 rest_get_server() 发送新的 nonce 到 X-WP-Nonce 头，以增强安全性。
原文内容
Checks for errors when using cookie-based authentication.
Description
WordPress’ built-in cookie authentication is always active for logged in users. However, the API has to check nonces for each request to ensure users are not vulnerable to CSRF.
Parameters
$resultWP_Error|mixedrequired-
Error from another authentication handler, null if we should handle it, or another value if not.
Source
function rest_cookie_check_errors( $result ) {
if ( ! empty( $result ) ) {
return $result;
}
global $wp_rest_auth_cookie;
/*
* Is cookie authentication being used? (If we get an auth
* error, but we're still logged in, another authentication
* must have been used).
*/
if ( true !== $wp_rest_auth_cookie && is_user_logged_in() ) {
return $result;
}
// Determine if there is a nonce.
$nonce = null;
if ( isset( $_REQUEST['_wpnonce'] ) ) {
$nonce = $_REQUEST['_wpnonce'];
} elseif ( isset( $_SERVER['HTTP_X_WP_NONCE'] ) ) {
$nonce = $_SERVER['HTTP_X_WP_NONCE'];
}
if ( null === $nonce ) {
// No nonce at all, so act as if it's an unauthenticated request.
wp_set_current_user( 0 );
return true;
}
// Check the nonce.
$result = wp_verify_nonce( $nonce, 'wp_rest' );
if ( ! $result ) {
add_filter( 'rest_send_nocache_headers', '__return_true', 20 );
return new WP_Error( 'rest_cookie_invalid_nonce', __( 'Cookie check failed' ), array( 'status' => 403 ) );
}
// Send a refreshed nonce in header.
rest_get_server()->send_header( 'X-WP-Nonce', wp_create_nonce( 'wp_rest' ) );
return true;
}
Changelog
| Version | Description |
|---|---|
| 4.4.0 | Introduced. |