WordPress at a glance

check_admin_referer() WP 1.2.0

Makes sure that a user was referred from another admin page. Also checks a nonce token. Stops php with die() in case of error.

If one of the checks failed, shows a message "Are you sure you want to do this?" with a link to the previous page, and then runs die() to stop further PHP execution. Read: wp_nonce_ays().

There's also a similiar function for AJAX requests: check_ajax_referer()

This is a pluggable function, and it can be replaced by a plugin. It means that this function is defined (works) only after all plugins are loaded (included), but before this moment this function has not defined. Therefore, you cannot call this and all functions depended on this function directly from a plugin code. It must be called on plugins_loaded hook or later, for example on init hook.

Function replacement (override) — in a plugin you can create a function with the same name, then it replace this function.

Hooks in function
Return

false/Int. False if the nonce is invalid, 1 if the nonce is valid and generated between
0-12 hours ago, 2 if the nonce is valid and generated between 12-24 hours ago.

Usage

check_admin_referer( $action, $query_arg );
$action(int/string)
Action nonce (the first argument of wp_nonce_field).
Default: -1
$query_arg(string)
Key to check for nonce in $_REQUEST (since 2.5).
Default: '_wpnonce'

Examples

#1 Basic example

<?php check_admin_referer( 'bcn_admin_options' ); ?>

Further PHP execution will be stopped if the request was made not from the dashboard.

#2 Adding and verifying of nonce token

Let's add a nonce token and referer field into the form with wp_nonce_field():

<form method="post">
	<!-- other fields ... -->
	<?php wp_nonce_field( 'name_of_my_action','name_of_nonce_field' ); ?>
</form>

Now, on the page where the request is handled, check the nonce token and referer, and process the request if the check is passed:

function my_handler_function(){
	check_admin_referer( 'name_of_my_action', 'name_of_nonce_field' );

	// process request
}

Or you can use if() for better readability:

if( check_admin_referer( 'name_of_my_action', 'name_of_nonce_field' ) ) {
   // process request
}

Code of check admin referer: wp-includes/pluggable.php VER 5.0.3

<?php
function check_admin_referer( $action = -1, $query_arg = '_wpnonce' ) {
	if ( -1 == $action )
		_doing_it_wrong( __FUNCTION__, __( 'You should specify a nonce action to be verified by using the first parameter.' ), '3.2.0' );

	$adminurl = strtolower(admin_url());
	$referer = strtolower(wp_get_referer());
	$result = isset($_REQUEST[$query_arg]) ? wp_verify_nonce($_REQUEST[$query_arg], $action) : false;

	/**
	 * Fires once the admin request has been validated or not.
	 *
	 * @since 1.5.1
	 *
	 * @param string    $action The nonce action.
	 * @param false|int $result False if the nonce is invalid, 1 if the nonce is valid and generated between
	 *                          0-12 hours ago, 2 if the nonce is valid and generated between 12-24 hours ago.
	 */
	do_action( 'check_admin_referer', $action, $result );

	if ( ! $result && ! ( -1 == $action && strpos( $referer, $adminurl ) === 0 ) ) {
		wp_nonce_ays( $action );
		die();
	}

	return $result;
}

Related Functions

From tag: nonce (security protection defence)

More from category: Security

No comments
    Hello, !     Log In . Register