Security Debug Information Display

Overview

The Security Debug Information feature provides developers and administrators with detailed insights into the authorization system during development. This feature displays user policies and tracks all authorization checks performed during a page request.

Features

1. Debug Mode Only

• Only active when Configure::read('debug') is true
• No performance impact in production environments
• Authorization tracking is conditionally enabled

2. User Policies Display

Shows all policies assigned to the current user with:

• Policy class and method names
• Scoping rules (Global, Branch Only, Branch and Children)
• Associated branch IDs

3. Authorization Check Log

Tracks and displays all authorization checks performed during the request:

• Action being checked (e.g., ‘view’, ‘edit’, ‘delete’)
• Resource being accessed (entity type and ID)
• Result (granted or denied)
• Additional arguments passed to policy methods
• Sequential order of checks

4. Interactive UI

• Toggle button in the footer: “Show Security Info”
• Smooth slide animations
• Responsive Bootstrap-styled tables
• Color-coded results (green for granted, red for denied)

Architecture

Components

1. AuthorizationService (src/Services/AuthorizationService.php)

Enhanced to track authorization checks:

public function checkCan(?KmpIdentityInterface $user, string $action, $resource, ...$optionalArgs): bool
{
    // ... authorization logic ...
    
    // Only log in debug mode
    if (\Cake\Core\Configure::read('debug')) {
        $this->logAuthCheck($user, $action, $resource, $resultBool, $optionalArgs);
    }
    
    return $resultBool;
}

Key methods:

• logAuthCheck() - Records authorization attempts
• getAuthCheckLog() - Retrieves log for display
• clearAuthCheckLog() - Clears the log

2. SecurityDebugHelper (src/View/Helper/SecurityDebugHelper.php)

View helper for rendering security information:

• displaySecurityInfo() - Main display method
• displayUserPolicies() - Renders user policy table
• displayAuthorizationChecks() - Renders authorization check log

3. Stimulus Controller (assets/js/controllers/security-debug-controller.js)

JavaScript controller for interactive UI:

• Toggle visibility of debug panel
• Smooth animations
• Session-persistent state

4. Footer Template (templates/element/copyrightFooter.php)

Integrated display in application footer:

• Only visible in debug mode
• Accessible from any page
• Non-intrusive placement

Usage

Viewing Security Information

1. Enable debug mode in config/app.php or config/.env:

   'debug' => true,
   

2. Navigate to any page in the application while logged in

3. Scroll to the footer and click “Show Security Info”

4. Review:
   • Your assigned policies and their scope
   • All authorization checks performed on the page
   • Which checks passed or failed

Interpreting Policy Display

Policy Table Columns:

• Policy Class: The policy handling authorization (e.g., MemberPolicy)
• Method: The specific check method (e.g., canView, canEdit)
• Scope: Authorization scope
  • 🔵 Global: Access to all branches
  • 🔵 Branch Only: Access limited to specific branches
  • 🟢 Branch + Children: Access to branch and descendants
• Branches: Specific branch IDs (or “All branches” for global)

Interpreting Authorization Log

Log Table Columns:

• #: Sequential order of checks
• Action: The action being checked (e.g., ‘view’, ‘edit’)
• Resource: Entity being accessed (e.g., ‘Member #123’)
• Result: ✓ Granted (green) or ✗ Denied (red)
• Args: Number of additional arguments passed

Color Coding:

• 🟢 Green row: Authorization granted
• 🔴 Red row: Authorization denied

Development Workflow

Debugging Authorization Issues

1. Reproduce the issue: Navigate to the page with authorization problems

2. Check the log: Click “Show Security Info” to see all authorization checks

3. Identify failed checks: Look for red (denied) entries

4. Verify user policies: Confirm the user has the required policy/method

5. Check scope: Ensure branch IDs match if scope is branch-specific

Common Scenarios

Scenario 1: User can’t access a page

• Look for denied checks early in the log
• Verify user has the policy method (e.g., canView)
• Check if branch scope matches the resource

Scenario 2: Button/action is hidden

• Find the authorization check for that action
• Verify the policy method exists for the user
• Check if the check is even being performed

Scenario 3: Unexpected access granted

• Look for checks that succeed unexpectedly
• Verify scoping rules are correct
• Check if user has unintended global permissions

Performance Considerations

Debug Mode Only

• Authorization tracking only occurs when debug mode is enabled
• Zero performance impact in production
• Log data is stored in memory for the request duration

Memory Usage

• Log entries are lightweight (< 1KB each typically)
• Cleared at end of request
• No database or file I/O

Best Practices

• Don’t enable debug mode in production
• Use this feature during development and testing
• Clear understanding of authorization flow before production deployment

Security Considerations

Information Exposure

• Only available in debug mode
• Assumes debug mode is disabled in production
• Does not expose passwords or sensitive credentials
• Shows authorization structure, not data content

Production Safety

Multiple layers prevent accidental exposure:

1. Debug mode configuration check
2. Button only rendered in debug mode
3. Tracking only occurs in debug mode
4. Helper returns empty string if not in debug mode

Integration with KMP Authorization System

Policy System

Works with KMP’s existing policy infrastructure:

• BasePolicy and derived policy classes
• _hasPolicy() method for permission checks
• Branch scoping (Global, Branch Only, Branch and Children)
• Permission-based authorization

Identity System

Integrates with KmpIdentityInterface:

• getPolicies() - Retrieves user policies
• isSuperUser() - Super user detection
• Permission and role system

Troubleshooting

Security Info Not Visible

Problem: “Show Security Info” button doesn’t appear

Solutions:

• Verify debug mode is enabled: Configure::read('debug')
• Clear cache: bin/cake cache clear_all
• Check browser console for JavaScript errors

Empty Authorization Log

Problem: No checks appear in the log

Solutions:

• Ensure page performs authorization checks
• Verify you’re logged in
• Some pages may not require authorization

Incorrect Policy Display

Problem: Policies shown don’t match expectations

Solutions:

• Clear permission cache: bin/cake cache clear _kmp_cache_
• Verify user roles and permissions in database
• Check PermissionsLoader configuration

Future Enhancements

Potential improvements:

• Filter log by action type
• Export log to JSON/CSV
• Stack trace for each authorization check
• Policy rule explanation
• Performance metrics (time per check)
• Historical comparison across requests

Related Documentation

• RBAC Security Architecture
• Authorization Helpers
• Security Best Practices
• Testing Infrastructure

Code References

Modified Files

• app/src/Services/AuthorizationService.php - Authorization tracking
• app/src/View/Helper/SecurityDebugHelper.php - Display helper
• app/src/View/AppView.php - Helper registration
• app/templates/element/copyrightFooter.php - UI integration
• app/assets/js/controllers/security-debug-controller.js - Interactive UI
• app/assets/js/index.js - Controller registration

Key Classes

• \App\Services\AuthorizationService - Core authorization with tracking
• \App\View\Helper\SecurityDebugHelper - Security info rendering
• \App\Policy\BasePolicy - Base policy with branch scoping
• \App\KMP\KmpIdentityInterface - User identity interface

Example Output

User Policies Table

┌──────────────────┬─────────────────┬───────────────────────┬──────────────┐
│ Policy Class     │ Method          │ Scope                 │ Branches     │
├──────────────────┼─────────────────┼───────────────────────┼──────────────┤
│ MemberPolicy     │ canView         │ 🔵 Global             │ All branches │
│                  │ canEdit         │ 🔵 Branch Only        │ 1, 5, 12     │
│                  │ canDelete       │ 🟢 Branch + Children  │ 1, 5         │
└──────────────────┴─────────────────┴───────────────────────┴──────────────┘

Authorization Check Log

┌───┬─────────┬──────────────┬────────────┬──────┐
│ # │ Action  │ Resource     │ Result     │ Args │
├───┼─────────┼──────────────┼────────────┼──────┤
│ 1 │ view    │ Member #123  │ ✓ Granted  │ 0    │
│ 2 │ edit    │ Member #123  │ ✓ Granted  │ 1    │
│ 3 │ delete  │ Member #456  │ ✗ Denied   │ 0    │
└───┴─────────┴──────────────┴────────────┴──────┘