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.
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'
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.
More Information
- Using the function without the
$action
argument is obsolete and, as of Version 3.2, ifWP_DEBUG
is set totrue
, 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.
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; }
Expand full source codeCollapse full source codeView on TracView on GitHub
Changelog
Version | Description |
---|---|
2.5.0 | The $query_arg parameter was added. |
1.2.0 | Introduced. |