how-to/troubleshoot-permissions.md

title: Troubleshooting the Permission System

Permission System Debugging Guide

Step 1: Sync Permissions

Call the identity service to sync permissions from all components:

# Replace <identity-port> with the actual port (check Aspire dashboard)
curl -X POST http://localhost:<identity-port>/permissions/sync

Expected Response:

{
  "message": "Permission synchronization completed successfully",
  "timestamp": "2025-11-05T..."
}

Step 2: Verify Permissions in Database

Check that permissions were created:

# Connect to PostgreSQL (replace <port> with actual port from Aspire Dashboard)
psql postgresql://localhost:<port>/acsis

# Check permissions table
SELECT full_name, display_name FROM identity.permissions WHERE full_name LIKE 'spatial:regions:%';

Expected Output:

         full_name          |   display_name
----------------------------+------------------
 spatial:regions:read       | View regions
 spatial:regions:create     | Create new regions
 spatial:regions:update     | Modify regions
 spatial:regions:delete     | Delete regions

Step 3: Check User's Session Token (Browser Console)

In the browser console on the regions page:

// Get the session from NextAuth
import { getSession } from 'next-auth/react';
const session = await getSession();

// Check if permissions exist
console.log('User permissions:', session?.user?.permissions);

// Check specific permission
console.log('Has create permission:', session?.user?.permissions?.includes('spatial:regions:create'));

Step 4: If Permissions Missing from JWT

The user needs to:

Have a role with permissions assigned (need admin to set this up)
Log out and log back in to get a fresh JWT with permissions

To Assign Permissions to a Role (Admin Required)

You'll need to create an admin endpoint or use the database directly:

-- Get your user's role
SELECT r.id, r.name
FROM identity.roles r
JOIN identity.user_roles ur ON ur.roles_id = r.id
JOIN identity.users u ON u.id = ur.users_id
WHERE u.username = 'your-username';

-- Get the permission ID
SELECT id, full_name FROM identity.permissions WHERE full_name = 'spatial:regions:create';

-- Assign permission to role
INSERT INTO identity.role_permissions (roles_id, permissions_id)
VALUES (
  (SELECT id FROM identity.roles WHERE name = 'YourRoleName'),
  (SELECT id FROM identity.permissions WHERE full_name = 'spatial:regions:create')
);

Step 5: Log Out and Back In

After assigning permissions:

Log out of the UI
Log back in
The new JWT will have the permissions
The "Create" button should appear!

Quick Check: Does User Have Legacy Menus?

The permission system has a fallback to the old menu system. Check if the user has the legacy menu:

// In browser console
const session = await getSession();
console.log('User menus:', session?.user?.menus);
console.log('Has legacy menu:', session?.user?.menus?.includes('regions/create'));

If the user has 'regions/create' in their menus array, the button should show even without the new permission system.

Documentation