WordPress.org

Languages: English • 日本語 (Add your language)

Description

Tests either if the current request carries a valid nonce, or if the current request was referred from an administration screen; depending on whether the $action argument is given (which is prefered), or not, respectively. On failure, the function dies after calling the wp_nonce_ays() function.

Used to avoid CSRF security exploits. Nonces should never be relied on for authentication or authorization, access control. Protect your functions using current_user_can(), always assume Nonces can be compromised.

The now improper name of the function is kept for backward compatibility and has origin in previous WordPress versions where the function only checked the referer. For details, see the Notes section below.

Usage

Obsolete Usage

<?php check_admin_referer(); ?>

Prefered Usage

<?php check_admin_referer( $action, $query_arg ); ?>

Parameters

$action

(string) (optional) Action name. Should give the context to what is taking place. (Since 2.0.1).

Default: -1

$query_arg

(string) (optional) Where to look for nonce in the $_REQUEST PHP variable. (Since 2.5).

Default: '_wpnonce'

Return

To return boolean true, in the case of the obsolete usage, the current request must be referred from an administration screen; in the case of the prefered usage, the nonce must be sent and valid. Otherwise the function dies with an appropriate message ("Are you sure you want to do this?" by default).

Examples

Here is an example of how you might use this in a plugin's option page. You add a nonce to a form using the wp_nonce_field() function:

<form method="post">
   <!-- some inputs here -->
   <?php wp_nonce_field( 'name_of_my_action', 'name_of_nonce_field' ); ?>
</form>

Then in the page where the form submits to, you can verify whether or not the form was submitted and update values if it was successfully submitted:

<?php
check_admin_referer( 'name_of_my_action', 'name_of_nonce_field' );
// process form data, e.g. update fields
// you can use it in a IF statement if you want, not mandatory because there is not "false" return, only true or die().

// Display the form

Notes

• Using the function without the $action argument is obsolete and, as of Version 3.2, if WP_DEBUG is set to true will die with an appropriate message ("You should specify a nonce action to be verified by using the first parameter." is the default).
• As of 2.0.1, the referer is checked only if the $action argument is not specified (or set to the default -1) as a backward compatibility fallback for not using a nonce. A nonce is prefered to unreliable referers and with $action specified the function behaves the same way as wp_verify_nonce() except that it dies after calling wp_nonce_ays() if the nonce is not valid or was not sent.

Change Log

Since: 1.2.0

Source File

check_admin_referer() is located in wp-includes/pluggable.php.

Related

Nonce functions: wp_nonce_ays(), wp_nonce_field(), wp_nonce_url(), wp_verify_nonce(), wp_create_nonce(), check_admin_referer(), check_ajax_referer(), wp_referer_field()

Nonce hooks: nonce_life, nonce_user_logged_out, explain_nonce_(verb)-(noun), check_admin_referer

• Wordpress Nonce Implementation

Resources

• PHP: die - Manual
• PHP: $_REQUEST - Manual
• Mark Jaquith - WordPress Nonces
• Vladimir Prelovac - Using Nonces in WordPress Plugins
• Cryptographic nonce - Wikipedia, the free encyclopedia
• wp_verify_nonce vs check_admin_referer - WordPress Answers
• WordPress Nonce Vulnerabilities | codeseekah.com
• This post explains how WordPress nonces really work - bynicolas.com