آموزش تابع wp_nonce_field() در وردپرس و کاربرد آن

تابع wp_nonce_field() یکی از ابزارهای مهم امنیتی در توسعه افزونه‌ها و قالب‌های وردپرس است. این تابع برای تولید یک فیلد مخفی در فرم‌ها استفاده می‌شود که به عنوان tokenِ موقت برای جلوگیری از حملات CSRF (Cross-Site Request Forgery) عمل می‌کند. در این مقاله به صورت کامل کاربردها، مثال‌ها، نحوه بررسی و بهترین شیوه‌ها توضیح داده می‌شود.

nonce در وردپرس چیست و چگونه کار می‌کند؟

در وردپرس واژه nonce کوتاه‌شدهٔ “number used once” نیست؛ بلکه یک توکن موقت است. nonce برای تایید اینکه درخواست از سمت کاربر واقعی و از طریق فرم یا درخواست معتبر ارسال شده، به کار می‌رود. nonces زمان‌داری (معمولاً 24 ساعت) و مبتنی بر کاربر، عمل و زمان هستند و برای جلوگیری از ارسال‌های جعلی طراحی شده‌اند.

چرا باید از wp_nonce_field() استفاده کنیم؟

• محافظت در برابر CSRF.
• تایید منشا درخواست (معمولاً از داخل سایت).
• سادگی پیاده‌سازی در فرم‌ها (تولید فیلد مخفی با نام و مقدار مناسب).

نحوۀ استفاده پایه: افزودن nonce به فرم

<form method="post" action="">
  <input type="text" name="my_field" />
  <?php wp_nonce_field( 'my_action', 'my_nonce_field' ); ?>
  <input type="submit" value="Send" />
</form>

در این مثال، wp_nonce_field دو پارامتر می‌گیرد: action که رشته‌ای برای شناسایی عملیات است (مثلاً ‘my_action’) و name که نام فیلد مخفی را تعیین می‌کند (مثلاً ‘my_nonce_field’). اگر نام فیلد را مشخص نکنید، وردپرس از مقدار پیش‌فرض _wpnonce استفاده می‌کند. همچنین پارامتر مرجع ($referrer) به‌صورت پیش‌فرض true است که فیلد _wp_http_referer را نیز اضافه می‌کند.

بررسی nonce هنگام پردازش فرم

if ( isset($_POST['my_nonce_field']) && wp_verify_nonce( $_POST['my_nonce_field'], 'my_action' ) ) {
    // پردازش امن فرم
    $value = sanitize_text_field( $_POST['my_field'] );
    // ذخیره یا پردازش داده
} else {
    // خطای معتبر نبودن nonce
    wp_die( 'کار غیرمجاز' );
}

در مثال بالا wp_verify_nonce() مقدار فرستاده‌شده را با action مشخص‌شده مقایسه می‌کند و در صورت معتبر بودن true برمی‌گرداند. معمولاً بعد از تایید nonce بهتر است داده‌ها را نیز بررسی و پاک‌سازی (sanitize) کنید و در صورت نیاز دسترسی کاربر را با current_user_can() چک کنید.

روش دیگر: check_admin_referer و check_ajax_referer

برای فرم‌های ادمین یا درخواست‌های AJAX می‌توانید از توابع کمکی استفاده کنید که هم nonce و هم referrer را بررسی می‌کنند.

// در پردازش فرم ادمین
check_admin_referer( 'my_action', 'my_nonce_field' );
// ادامه پردازش...

این تابع اگر nonce نامعتبر باشد، اجرای برنامه را متوقف و صفحه را ریدایرکت یا خطا می‌دهد. همین‌طور برای AJAX:

// در یک اکشن AJAX
check_ajax_referer( 'my_action', 'security' );

// یا اگر می‌خواهید مقدار بازگردد:
$nonce_check = check_ajax_referer( 'my_action', 'security', false );

پارامتر سوم در check_ajax_referer مشخص می‌کند که در صورت نامعتبر بودن چه رفتاری داشته باشد (مثلاً false تنها false برمی‌گرداند).

نمونه کامل: فرم سمت فرانت و پردازش

<form method="post" action="<?php echo esc_url( admin_url('admin-post.php') ); ?>">
  <input type="text" name="my_field" />
  <?php wp_nonce_field( 'save_my_data', 'save_my_data_nonce' ); ?>
  <input type="hidden" name="action" value="save_my_data_handler" />
  <input type="submit" value="Save" />
</form>

در فایل توابع یا افزونه:

add_action( 'admin_post_nopriv_save_my_data_handler', 'save_my_data_handler' );
add_action( 'admin_post_save_my_data_handler', 'save_my_data_handler' );

function save_my_data_handler() {
    if ( ! isset( $_POST['save_my_data_nonce'] ) || ! wp_verify_nonce( $_POST['save_my_data_nonce'], 'save_my_data' ) ) {
        wp_die( 'درخواست نامعتبر.' );
    }
    // پردازش ایمن داده
    $data = sanitize_text_field( $_POST['my_field'] );
    // ذخیره‌سازی یا عملیات لازم
    wp_redirect( home_url() );
    exit;
}

این الگو برای ارسال فرم از فرانت‌اند به admin-post.php رایج است و شامل احراز اعتبار nonce و پاکسازی داده‌ها می‌شود.

wp_nonce_url و wp_create_nonce

گاهی لازم است URL‌هایی را با nonce تولید کنید، مثلاً برای لینک حذف:

$delete_url = wp_nonce_url( add_query_arg( 'id', $id, admin_url('admin.php?page=my_page') ), 'delete_item_' . $id, 'delete_nonce' );

این تابع یک پارامتر nonce به URL اضافه می‌کند. همچنین wp_create_nonce() تنها مقدار nonce تولید می‌کند که می‌توانید در هدرها یا جاوااسکریپت استفاده کنید.

$nonce = wp_create_nonce( 'wp_rest' ); // برای REST API اغلب 'wp_rest' استفاده می‌شود

برای فراخوانی REST API از فرانت‌اند، معمولا این nonce را در جاوااسکریپت به عنوان X-WP-Nonce به هدر می‌فرستند.

میزان امنیت و محدودیت‌ها

• nonceها برای جلوگیری از CSRF مناسب‌اند اما جایگزین سیاست‌های کنترل دسترسی نیستند. همیشه سطح دسترسی کاربر را با current_user_can بررسی کنید.
• nonces زمان‌دارند (پیش‌فرض حدود 24 ساعت) و ممکن است در شرایط خاص خیلی محکم نباشند؛ نباید از آن‌ها برای انتقال داده‌های حساس یا رمزگذاری استفاده کنید.
• nonceها بر اساس کوکی و نشست کاربر/جلسه هستند؛ اگر کاربر لاگین نباشد، nonce بر مبنای اطلاعات دیگری تولید می‌شود که قابل تشخیص است.

جدول مقایسه توابع مربوط به nonce

بهترین شیوه‌ها و نکات تکمیلی

• همیشه از نام action یکتا و معنی‌دار استفاده کنید تا از برخورد جلوگیری شود (مثلاً: ‘delete_post_123’).
• پس از بررسی nonce، داده‌ها را حتماً پاک‌سازی و سپس عمل مورد نظر را انجام دهید.
• در AJAX از check_ajax_referer استفاده کنید و هدر مناسب (X-WP-Nonce) را برای REST API به کار برید.
• به یاد داشته باشید nonce جایگزین بررسی دسترسی کاربر نیست؛ همیشه current_user_can را چک کنید.

جمع‌بندی

تابع wp_nonce_field() و تابع‌های مرتبط ابزاری ساده و موثر برای افزایش امنیت فرم‌ها و درخواست‌ها در وردپرس هستند. با استفادهٔ درست از تولید و بررسی nonce، پاک‌سازی ورودی‌ها و چک کردن دسترسی کاربران می‌توانید ریسک حملات CSRF را به طور قابل توجهی کاهش دهید.

لطفاً از کمبود ها و مشکلات این محتوا برای ما بنویسید

ارسال