check_admin_referer() WordPress Function

The check_admin_referer() function is a security measure that helps to prevent cross-site request forgery (CSRF) attacks. This function checks the nonce (number used once) value in the current HTTP request against the nonce value that was stored in the user's session. If the two values match, then the request is considered to be valid and the function returns true. Otherwise, the function returns false and an error message is displayed.

check_admin_referer( int|string $action = -1, string $query_arg = '_wpnonce' ) #

Ensures intent by verifying that a user was referred from another admin page with the correct security nonce.


Description

This function ensures the user intends to perform a given action, which helps protect against clickjacking style attacks. It verifies intent, not authorisation, therefore it does not verify the user’s capabilities. This should be performed with current_user_can() or similar.

If the nonce value is invalid, the function will exit with an "Are You Sure?" style message.


Top ↑

Parameters

$action

(int|string)(Optional)The nonce action.

Default value: -1

$query_arg

(string)(Optional) Key to check for nonce in $_REQUEST.

Default value: '_wpnonce'


Top ↑

Return

(int|false) 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. False if the nonce is invalid.


Top ↑

More Information

  • Using the function without the $action argument is obsolete and, as of Version 3.2, if WP_DEBUG is set to true, the function 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.

Top ↑

Source

File: wp-includes/pluggable.php

	function check_admin_referer( $action = -1, $query_arg = '_wpnonce' ) {
		if ( -1 === $action ) {
			_doing_it_wrong( __FUNCTION__, __( 'You should specify an 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;
	}


Top ↑

Changelog

Changelog
VersionDescription
2.5.0The $query_arg parameter was added.
1.2.0Introduced.

The content displayed on this page has been created in part by processing WordPress source code files which are made available under the GPLv2 (or a later version) license by theĀ Free Software Foundation. In addition to this, the content includes user-written examples and information. All material is subject to review and curation by the WPPaste.com community.

Show More