Capability and Permission Systems: Advanced WordPress Access Control

Previously in this course, we discussed Nonce Management Architecture to prevent CSRF attacks. While nonces secure specific actions, they don't define who is authorized to perform them. Today, we bridge that gap by implementing a robust Access Control List (ACL) system using WordPress capabilities.

Understanding Capabilities vs. Roles

In WordPress, a Role is a collection of Capabilities. Never check for a user role (e.g., is_admin()) in your business logic. Roles are mutable; a site owner might rename "Editor" or create a "Custom Manager" role that lacks the permissions you expect.

Instead, we use Capabilities. A capability is a string (like edit_kb_articles) that acts as an abstract permission token. When you check current_user_can('edit_kb_articles'), WordPress calculates if the current user has that capability—either directly or via their assigned role.

Defining Custom Capabilities

For our Knowledge Base plugin, we need granular control. We don't want every contributor to be able to delete knowledge base entries. We define our capabilities during plugin activation to ensure they exist regardless of which role is active.

PHP
namespace KBPlugin\Security;

class CapabilityManager {
    public const CAP_MANAGE = 'manage_kb_entries';
    public const CAP_DELETE = 'delete_kb_entries';

    public function register_capabilities(): void {
        $roles = ['administrator', 'editor'];
        
        foreach ($roles as $role_name) {
            $role = get_role($role_name);
            if ($role) {
                $role->add_cap(self::CAP_MANAGE);
                $role->add_cap(self::CAP_DELETE);
            }
        }
    }
}

Implementing Capability Checks

Once defined, you must enforce these checks at the entry point of every sensitive action. This is the cornerstone of Capability Checks: Securing WordPress Plugins with Authorization.

Never assume the UI state reflects the backend reality. If a user can see a "Delete" button, you must re-verify their permission when the request hits the server.

PHP
#6A9955">// Inside a Controller or Service
public function delete_entry(int $id): bool {
    if (!current_user_can(CapabilityManager::CAP_DELETE)) {
        throw new \Exception('Unauthorized: Insufficient permissions.');
    }
    
    return $this->repository->delete($id);
}

Integrating with WordPress Roles

Sometimes, you need to map your custom capabilities to existing roles dynamically. You can hook into map_meta_cap to create "contextual" capabilities. This allows you to check for edit_kb_entry while passing the object ID, enabling fine-grained checks like "can this user edit this specific entry?"

PHP
add_filter('map_meta_cap', function($caps, $cap, $user_id, $args) {
    if ($cap === 'edit_kb_entry') {
        $post = get_post($args[0]);
        if ($post->post_author == $user_id) {
            return ['edit_posts']; #6A9955">// User owns it, they can edit
        }
    }
    return $caps;
}, 10, 4);

Hands-on Exercise

1. Create a SecurityServiceProvider that registers your plugin's capabilities on the init action (or during plugin activation).
2. Add a check in your Knowledge Base repository's save method.
3. Attempt to perform an action as a standard "Subscriber" user. Verify that the system correctly blocks the request.

Common Pitfalls

• Hardcoding Roles: Never check if (current_user_can('administrator')). Always use your custom capabilities. If you need to change permissions later, you update the capability mapping, not the code logic.
• Ignoring map_meta_cap: For object-level permissions (e.g., editing a specific post), relying solely on primitive capabilities is insufficient. Use map_meta_cap to verify ownership or status.
• Activation Hook Latency: Capabilities are stored in the wp_user_roles option. If you change your add_cap logic, you must manually run it again, as the activation hook only runs once. Use a versioning constant in your options table to trigger re-registration on plugin updates.

Advancing the Project

In our Knowledge Base plugin, we will now add a KB_CAP_MANAGE capability to our ServiceContainer. This ensures that all future REST API endpoints and admin menu items are protected by the same central authority. This directly prepares us for Implementing REST API Permission Callbacks for Secure Plugins.

Up next: Preventing SQL Injection.