研究 wp_signon 如何进行用户登录与 cookie 验证流程

WordPress 用户登录与 Cookie 验证流程详解

大家好，今天我们深入探讨 WordPress 的核心登录机制，特别是 wp_signon 函数以及它如何处理用户登录和 Cookie 验证。理解这些机制对于开发 WordPress 插件、主题，或者仅仅是想更深入地了解 WordPress 的工作方式至关重要。

一、wp_signon 函数：登录的入口

wp_signon 函数是 WordPress 中处理用户登录的主要入口点。它接收用户凭据（用户名和密码），验证这些凭据，并在验证成功后设置用户的身份验证 Cookie。

1. 函数签名和参数

wp_signon 函数定义在 wp-includes/pluggable.php 文件中，其签名如下：

function wp_signon( $credentials = array(), $secure_cookie = '' ) {
  // ... 函数体 ...
}

• $credentials (array, optional): 包含用户登录信息的数组。通常包含 user_login (用户名) 和 user_password (密码) 键。
• $secure_cookie (string|bool, optional): 是否强制使用安全 Cookie (HTTPS)。默认为空字符串，表示根据当前连接的安全性自动决定。

2. $credentials 数组的构建

通常，我们从用户提交的表单中获取用户名和密码，并将其放入 $credentials 数组中。例如：

$credentials = array();
$credentials['user_login'] = $_POST['username']; // 从表单获取用户名
$credentials['user_password'] = $_POST['password']; // 从表单获取密码
$credentials['remember'] = isset($_POST['rememberme']); // 是否记住登录状态

3. 函数内部流程：验证和 Cookie 设置

wp_signon 函数的内部流程可以概括为以下几个步骤：

1. 过滤凭据: 使用 wp_authenticate 过滤器，允许插件和主题修改或增强身份验证过程。这是 WordPress 可扩展性的一个关键点。
2. 验证用户: 调用 wp_authenticate 函数进行实际的用户名和密码验证。这个函数会依次尝试多种验证方法，包括从数据库中检索用户信息并比较哈希密码。
3. 处理验证结果: 如果验证成功，wp_authenticate 返回一个 WP_User 对象；如果验证失败，则返回一个 WP_Error 对象。
4. 设置 Cookie: 如果验证成功，调用 wp_set_auth_cookie 函数设置身份验证 Cookie。
5. 触发 Action: 触发 wp_login action，允许插件和主题在用户成功登录后执行自定义操作。
6. 返回 WP_User 对象: 返回验证成功的 WP_User 对象。

二、wp_authenticate 过滤器：灵活的身份验证

wp_authenticate 过滤器是 WordPress 身份验证机制的核心，它允许开发者在默认的身份验证过程前后插入自定义的验证逻辑。

1. 过滤器的工作方式

wp_authenticate 过滤器接收三个参数：

• $user (WP_User|WP_Error|null): 当前的用户对象。在身份验证过程的早期，这个参数通常为 null。如果前面的过滤器已经验证了用户，它可能包含一个 WP_User 对象。如果验证失败，它可能包含一个 WP_Error 对象。
• $username (string): 用户名。
• $password (string): 密码。

过滤器函数必须返回以下三种类型之一：

• WP_User: 如果身份验证成功，返回一个 WP_User 对象。
• WP_Error: 如果身份验证失败，返回一个 WP_Error 对象。
• null: 如果过滤器无法确定用户的身份，返回 null，让后续的过滤器继续尝试验证。

2. 使用示例：添加自定义身份验证方法

假设我们想添加一种基于电子邮件地址的身份验证方法。我们可以使用 wp_authenticate 过滤器来实现：

add_filter( 'wp_authenticate', 'my_custom_authenticate', 30, 3 );

function my_custom_authenticate( $user, $username, $password ) {
  // 检查是否已经验证了用户
  if ( !is_null( $user ) ) {
    return $user;
  }

  // 使用电子邮件地址查找用户
  $user_data = get_user_by( 'email', $username );

  if ( !$user_data ) {
    return null; // 找不到用户，让后续的过滤器继续
  }

  // 验证密码
  if ( wp_check_password( $password, $user_data->user_pass, $user_data->ID ) ) {
    return new WP_User( $user_data->ID ); // 验证成功
  } else {
    return null; // 密码错误，让后续的过滤器继续
  }
}

在这个例子中，我们首先检查是否已经验证了用户。如果没有，我们使用电子邮件地址查找用户。如果找到了用户，我们验证密码。如果验证成功，我们返回一个 WP_User 对象；否则，我们返回 null，让后续的过滤器继续尝试验证。

三、wp_set_auth_cookie 函数：Cookie 的设置

wp_set_auth_cookie 函数负责设置 WordPress 的身份验证 Cookie。这些 Cookie 用于在用户浏览网站时保持用户的登录状态。

1. 函数签名和参数

function wp_set_auth_cookie( $user_id, $remember = false, $secure = '' ) {
  // ... 函数体 ...
}

• $user_id (int): 用户的 ID。
• $remember (bool, optional): 是否记住登录状态。如果为 true，Cookie 的有效期会更长。
• $secure (string|bool, optional): 是否强制使用安全 Cookie (HTTPS)。默认为空字符串，表示根据当前连接的安全性自动决定。

2. Cookie 的类型

wp_set_auth_cookie 函数设置三种类型的 Cookie：

• wordpress_logged_in_[hash]: 用于验证用户是否已登录。这个 Cookie 包含用户名、过期时间和哈希值。
• wordpress_[hash]: 用于自动登录 (如果选择了 "记住我")。这个 Cookie 包含用户名、过期时间和哈希值。
• wp-settings-[UID] 和 wp-settings-time-[UID]: 存储用户的设置。这些 Cookie 不是严格意义上的身份验证 Cookie，但它们与用户体验相关。

3. Cookie 的哈希值

Cookie 的哈希值是通过对用户名、密码哈希、过期时间和盐 (salt) 进行哈希计算得到的。盐是随机生成的字符串，用于增加哈希值的安全性。WordPress 使用 wp_salt 函数生成盐。

4. 代码示例

// 获取用户 ID
$user = get_user_by( 'login', $_POST['username'] ); //假设用户名已经验证过
$user_id = $user->ID;

// 设置 Cookie
wp_set_auth_cookie( $user_id, isset($_POST['rememberme']), is_ssl() );

// 设置用户 ID Cookie
setcookie( 'wp_user_id', $user_id, time() + ( 3600 ), COOKIEPATH, COOKIE_DOMAIN );

// 重定向到管理页面
wp_safe_redirect( admin_url() );
exit;

四、wp_validate_auth_cookie 函数：Cookie 的验证

wp_validate_auth_cookie 函数用于验证身份验证 Cookie，以确定用户是否已登录。这个函数在每次页面加载时都会被调用，以检查用户是否需要重新登录。

1. 函数签名和参数

function wp_validate_auth_cookie( $cookie = '', $scheme = '' ) {
  // ... 函数体 ...
}

• $cookie (string, optional): 要验证的 Cookie 的值。如果为空，函数会尝试从 $_COOKIE 数组中获取 Cookie。
• $scheme (string, optional): 身份验证方案。可以是 ‘auth’ (默认), ‘secure’ (HTTPS), 或 ‘logged_in’。

2. 验证流程

wp_validate_auth_cookie 函数的验证流程如下：

1. 获取 Cookie 值: 如果 $cookie 参数为空，函数会尝试从 $_COOKIE 数组中获取 wordpress_logged_in_[hash] Cookie 的值。
2. 解析 Cookie 值: 函数解析 Cookie 值，提取用户名、过期时间和哈希值。
3. 验证哈希值: 函数使用相同的算法重新计算哈希值，并将其与 Cookie 中的哈希值进行比较。如果哈希值不匹配，则 Cookie 无效。
4. 检查过期时间: 函数检查 Cookie 是否已过期。如果已过期，则 Cookie 无效。
5. 加载用户信息: 如果 Cookie 有效，函数使用用户名从数据库中加载用户信息。
6. 返回 WP_User 对象: 如果用户信息加载成功，函数返回一个 WP_User 对象；否则，返回 false。

3. 使用示例

// 验证 Cookie
$user = wp_validate_auth_cookie();

if ( $user ) {
  // 用户已登录
  echo 'Welcome, ' . $user->user_login . '!';
} else {
  // 用户未登录
  echo '<a href="' . wp_login_url() . '">Login</a>';
}

五、 Cookie 验证过程中的 Scheme

wp_validate_auth_cookie函数和wp_set_auth_cookie函数都涉及到一个$scheme参数，这个参数决定了使用哪种验证方案。WordPress 定义了三种主要的方案：

• ‘auth’: 这是默认的方案，用于普通的身份验证。
• ‘secure’: 用于 HTTPS 连接，确保 Cookie 只能通过加密连接发送。
• ‘logged_in’: 用于wordpress_logged_in_[hash] Cookie，表明用户已登录。

选择正确的方案对于安全性和用户体验至关重要。在 HTTPS 连接上，应该始终使用 ‘secure’ 方案。

六、代码示例：完整的登录流程

下面是一个完整的示例，演示如何使用 wp_signon 函数进行用户登录和 Cookie 验证：

<?php
// 处理登录表单提交

if ( isset( $_POST['login'] ) ) {
  $username = sanitize_user( $_POST['username'] );
  $password = $_POST['password'];
  $remember = isset( $_POST['rememberme'] );

  $credentials = array();
  $credentials['user_login'] = $username;
  $credentials['user_password'] = $password;
  $credentials['remember'] = $remember;

  $user = wp_signon( $credentials, is_ssl() );

  if ( is_wp_error( $user ) ) {
    echo '<p class="error">' . $user->get_error_message() . '</p>';
  } else {
    // 登录成功，重定向到管理页面或首页
    wp_safe_redirect( admin_url() );
    exit;
  }
}

// 显示登录表单
?>
<form method="post">
  <p>
    <label>Username:<br>
      <input type="text" name="username" size="20"></label>
  </p>
  <p>
    <label>Password:<br>
      <input type="password" name="password" size="20"></label>
  </p>
  <p>
    <label>
      <input type="checkbox" name="rememberme" value="forever"> Remember Me</label>
  </p>
  <p>
    <input type="submit" name="login" value="Log In">
  </p>
</form>

<?php
// 在每个页面加载时验证 Cookie
$current_user = wp_validate_auth_cookie();

if ( $current_user ) {
  // 用户已登录
  echo '<p>Welcome, ' . $current_user->user_login . '! <a href="' . wp_logout_url() . '">Logout</a></p>';
} else {
  // 用户未登录
  echo '<p>You are not logged in. <a href="' . wp_login_url() . '">Login</a></p>';
}
?>

七、安全性考虑

在处理用户登录和 Cookie 验证时，安全性至关重要。以下是一些需要考虑的关键点：

• 使用 HTTPS: 始终使用 HTTPS 连接，以防止 Cookie 被窃取。
• 密码哈希: 使用强密码哈希算法 (如 bcrypt) 存储密码。WordPress 已经内置了 wp_hash_password 和 wp_check_password 函数来处理密码哈希。
• 防止 CSRF: 使用 nonce (一次性令牌) 来防止跨站请求伪造 (CSRF) 攻击。
• 输入验证和转义: 验证和转义所有用户输入，以防止跨站脚本 (XSS) 攻击和 SQL 注入攻击。
• 定期更新: 定期更新 WordPress 和所有插件，以修复安全漏洞。
• 双因素认证 (2FA): 考虑使用双因素认证，以增加账户安全性。

八、Cookie相关的函数总结

函数名	描述
wp_signon()	用户登录的核心函数，接收用户名和密码，验证，设置Cookie并返回用户对象。
wp_authenticate 过滤器	允许自定义身份验证逻辑，可以在默认验证前后插入自定义的验证步骤。
wp_set_auth_cookie()	设置身份验证Cookie，包括登录状态、记住我等信息。
wp_validate_auth_cookie()	验证身份验证Cookie，检查是否有效和过期，用于确定用户是否已登录。
wp_logout_url()	生成注销链接，用户点击后会清除Cookie并重定向到指定页面。
wp_login_url()	生成登录链接，用于引导用户到登录页面。
wp_hash_password()	对密码进行哈希处理，用于安全存储密码。
wp_check_password()	验证用户输入的密码是否与存储的哈希密码匹配。
is_ssl()	检查当前连接是否为HTTPS。
setcookie()	PHP原生函数，用于设置Cookie。WordPress的Cookie相关函数底层也依赖于此函数。

九、理解登录和验证机制是开发安全插件的关键

通过上述分析，我们了解了 wp_signon 函数以及相关的 Cookie 验证机制在 WordPress 中的作用。理解这些机制对于开发安全的 WordPress 插件和主题至关重要。通过利用 wp_authenticate 过滤器，我们可以添加自定义的身份验证方法。通过正确地设置和验证 Cookie，我们可以确保用户在浏览网站时保持登录状态。最重要的是，我们必须始终牢记安全性，并采取适当的措施来保护用户数据。