WordPress Nonce 101: What are they and why do they matter?

If your plugin has its own settings page and performs any kind of CRUD (Create, Read, Update, Delete) action, then you should be using nonces.

If you’ve never heard of the term nonce before, WordPress defines it in the codex as, “number used once”. Once a nonce is used, it cannot be used again—a one-time token.

WordPress provides some easy methods and functions to include nonces within certain features to guard against malicious requests.

Using nonces is critical to the security of your plugin

You should be using nonces:

  • When changing user data
  • When updating or creating posts
  • When updating settings and user preferences

Any time users are submitting a form and you are performing database modifications, you should be relying on a nonce to verify that the request is authenticated by a user with the correct permissions.

How do nonces prevent malicious attacks?

Since a nonce is a “number used once”, they are used to validate that when a request is sent, the request was initiated by an authenticated user.

Consider this link:

<a href="<https://yoursite.com/wp-admin/post.php?post=123&action=trash>">Trash Post</a>

If your browser is currently logged into your website and has an authenticated cookie stored, this would send the post to the trash.

Imagine then, a malicious user embedding this on their site:

<img src="<https://yoursite.com/wp-admin/post.php?post=123&action=trash>">

You wouldn’t know the site is sending a request to that URL and the next time you visited your site, that post would be trashed.

This is a simple example and attacks can be much more sophisticated, but it demonstrates why nonces are critical.

If a nonce validation is implemented with that trash post request (which it is), then when that malicious site tries to delete your post, the request will fail because an authenticated nonce isn’t included.

How do you use nonces in your plugin?

WordPress includes helper functions that make nonces quick to include.

To add a hidden nonce field for the delete post example we used earlier:

wp_nonce_field( 'trash-post-' . $post_id );

You pass a clear description of the action taking place with the nonce and WordPress will create a token for it.

To validate the nonce before performing your action (i.e. after form submission):

 * Trashes a post on form submission.
function trash_post() {
	// Before you do anything here, check the nonce with the same action key.
  check_admin_referer( 'delete-post-' . $_POST['post'] );
	// Nonce is valid.
  wp_trash_post( $_POST['post'] );

add_action( 'init', 'trash_post' );

check_admin_referer() validates that the nonce was included with the request and actually validates the nonce itself.

If the validation fails for any reason, a 403 Forbidden error is thrown for the user and the action is prevented—preventing unauthenticated requests from trashing our post.

In Summary

Nonces are critical to the security of user request in your plugin code.

Without nonces, data stored in your database could be modified by malicious users.

With two lines of additional code, you can implement nonces in all your plugin settings pages.

Interested in learning more about nonces? Dig into the codex and learn all the additional features so you can implement nonces in other ways (as I’ve only covered a simple use case).