Troubleshooting permissions

This guide provides solutions for common permission and access control issues. Use it when users report problems accessing features or data.

---

Quick diagnosis checklist

Before diving into specific issues, verify these basics:

• User account is active (isActive: true)
• User has logged in recently (session valid)
• User has at least one role assigned
• Correct school/organization is selected
• No active account lock (lockedUntil)

---

Common issues and solutions

Issue: User cannot see a menu item

Symptoms:

• Navigation menu missing expected item
• Tab or section not visible
• Feature appears hidden

Diagnosis:

1. Check user's assigned roles:

   Users -> [User] -> Roles tab

2. Verify role has the required permission:

   Roles -> [Role] -> Permissions tab

3. Check the permission needed:

   Menu item	Required permission
   Students	students.view
   Teachers	teachers.view
   Finance	finance.view
   Settings	settings.view
   Users	users.view
   Audit	audit.view

Solution:

• Add missing permission to role, OR
• Assign additional role with permission, OR
• Create custom role with needed access

---

Issue: "Access denied" error

Symptoms:

• Error message when clicking button
• Action fails with permission error
• Form submission rejected

Diagnosis:

1. Note the exact action attempted
2. Check user's effective permissions:

   Users -> [User] -> Permissions tab -> View effective

3. Verify permission source (role vs direct)

Common causes:

Cause	Fix
Permission not granted	Add to role
Wrong scope selected	Select correct school
Role assignment expired	Renew assignment
Policy blocking	Review ABAC policies

Solution:

• Identify the specific permission needed
• Grant via role (preferred) or directly

---

Issue: User can view but cannot edit

Symptoms:

• Data displays but fields are read-only
• Edit button missing or disabled
• Save button doesn't appear

Explanation:

View and edit are separate permissions:

• resource.view - Read access only
• resource.update - Edit access needed

Solution:

• Add the *.update permission for the resource
• Or assign a role that includes edit access

---

Issue: User can see some records but not others

Symptoms:

• Partial data visible
• "Record not found" for specific items
• Different results than admin sees

Diagnosis:

This usually indicates scoped access:

1. Organization scope - User may only see records in their school/department
2. Resource grants - Access limited to specific instances
3. ABAC policy - Conditional rules filtering data

Check:

Users -> [User] -> Role assignments
  -> Verify organization unit scope

Solution:

• Expand organization scope, OR
• Grant access to specific resources, OR
• Review/adjust ABAC policies

---

Issue: New role not taking effect

Symptoms:

• Role assigned but permissions don't work
• User still has old access level
• Changes not reflected

Diagnosis:

1. Assignment not active

   Check: isActive = true on assignment

2. Assignment expired

   Check: expiresAt (if set)

3. Session cache

   User needs to log out and back in

4. Wrong organization scope

   Role may be scoped to different school

Solution:

• Verify assignment is active and not expired
• Have user log out and back in
• Check organization unit matches context

---

Issue: Permission worked before, now doesn't

Symptoms:

• Feature used to work
• Now getting access denied
• No obvious change

Possible causes:

Cause	How to check
Role modified	Audit logs -> Role changes
Permission removed	Roles -> [Role] -> Permissions
Assignment expired	Users -> [User] -> Roles
Policy changed	Policies -> Recent changes
Account status changed	Users -> [User] -> Status

Solution:

• Review audit log for recent changes
• Restore permission or assignment as needed

---

Issue: Cannot access other school's data

Symptoms:

• User is admin but can't see other school
• Data visible in one school, not another
• Cross-school features don't work

Explanation:

Access is typically scoped by organization:

Tenant Admin -> All schools
School Admin -> Only their school(s)
Teacher -> Only their school

Solution:

• For Tenant Admin access: Assign Tenant Admin role
• For specific school: Add role with that school scope
• For temporary: Use resource grants

---

Issue: Guardian cannot see child's data

Symptoms:

• Parent logged in but no student data
• "No students linked" message
• Guardian portal empty

Diagnosis:

1. Verify guardian-student link:

   Students -> [Student] -> Guardians tab

2. Check guardian account is active

3. Verify guardian role assigned

Solution:

• Link guardian to student record
• Activate guardian account
• Assign Guardian role

---

Issue: Student cannot access portal

Symptoms:

• Student login fails
• Portal shows no data
• Access denied messages

Checklist:

1. Student user account exists
2. Account is active
3. Student role assigned
4. Student record linked to user
5. Enrollment is current

Solution:

• Create/activate user account
• Link to student record
• Verify current enrollment

---

Issue: MFA blocking access

Symptoms:

• Login succeeds but MFA fails
• "MFA required" but can't complete
• Locked out after MFA attempts

Solutions by scenario:

Scenario	Solution
Lost authenticator	Use backup codes
No backup codes	Admin reset MFA
SMS not received	Check phone number, try again
TOTP wrong code	Sync device time

Admin reset MFA:

Users -> [User] -> Security -> Reset MFA

---

Issue: Session terminated unexpectedly

Symptoms:

• Logged out without warning
• Work lost
• Frequent re-authentication

Possible causes:

Cause	Fix
Idle timeout	Work within timeout or request extension
Session limit	Check max sessions setting
Admin terminated	Contact admin
Security policy	Review login location/device
Token refresh failed	Clear cookies, log in fresh

---

Issue: Device not recognized

Symptoms:

• "Unknown device" warnings
• Extra verification required
• Device trust prompts

Explanation:

Device fingerprint changed due to:

• Browser update
• Cleared cookies
• Incognito mode
• VPN change

Solution:

• Trust the device when prompted
• For frequent use, avoid incognito
• Maintain consistent VPN usage

---

Debugging permission issues

Step 1: Identify the permission

Determine what permission is needed:

1. Note the exact action failing
2. Check documentation for required permission
3. Look in browser console for permission name

Step 2: Check user's permissions

View effective permissions:

Foundation -> IAM -> Users -> [User] -> Permissions

The "Effective Permissions" view shows:

• All permissions user has
• Source (which role)
• Direct assignments

Step 3: Trace the permission path

For missing permission:

Is permission in any user's role?
  No -> Add to role or assign role with it
  
  Yes -> Is role assigned to user?
    No -> Assign the role
    
    Yes -> Is assignment active?
      No -> Activate or renew
      
      Yes -> Is scope correct?
        No -> Adjust organization scope
        
        Yes -> Check ABAC policies

Step 4: Check for denials

ABAC policies can explicitly deny:

Foundation -> IAM -> Policies
Filter: effect = deny

A deny policy overrides all grants.

Step 5: Review audit log

Check what changed:

Foundation -> Audit -> Logs
Filter: resource = users OR roles OR permissions
Filter: user = [affected user]

---

Permission error messages

Error message	Meaning	Solution
"Permission denied"	Missing required permission	Add permission
"Access denied"	Authorization failed	Check role/scope
"Not authorized"	Not logged in or session invalid	Re-authenticate
"Forbidden"	Server rejected request	Check all permission layers
"Resource not found"	May be access scope issue	Check organization scope

---

Escalation path

If you cannot resolve:

1. Document the issue:

   • User email/ID
   • Exact action attempted
   • Exact error message
   • Current roles and permissions

2. Check for related:

   • Is this one user or multiple?
   • Is this one action or multiple?
   • When did it start?

3. Escalate with:

   • Screenshots
   • Audit log excerpts
   • Steps to reproduce

---

Preventive measures

Regular audits

• Monthly: Review active user count
• Quarterly: Review role assignments
• Quarterly: Review custom roles
• Annually: Full permission audit

Change management

• Document permission changes
• Test changes with sample user
• Notify affected users
• Keep rollback plan

User training

• Explain role-based access
• Document how to request access
• Provide self-service where appropriate

---

Related documentation

• Security architecture - Role matrix and recommendations
• Identity & access management - Detailed IAM guide
• Sessions, MFA & device trust - Authentication issues
• Audit & compliance - Finding what changed