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:
-
Check user's assigned roles:
Users → [User] → Roles tab -
Verify role has the required permission:
Roles → [Role] → Permissions tab -
Check the permission needed:
Menu item Required permission Students students.viewTeachers teachers.viewFinance finance.viewSettings settings.viewUsers users.viewAudit 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:
- Note the exact action attempted
- Check user's effective permissions:
Users → [User] → Permissions tab → View effective - 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 onlyresource.update— Edit access needed
Solution:
- Add the
*.updatepermission 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:
- Organization scope — User may only see records in their school/department
- Resource grants — Access limited to specific instances
- 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:
-
Assignment not active
Check: isActive = true on assignment -
Assignment expired
Check: expiresAt (if set) -
Session cache
User needs to log out and back in -
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:
-
Verify guardian-student link:
Students → [Student] → Guardians tab -
Check guardian account is active
-
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:
- Student user account exists
- Account is active
- Student role assigned
- Student record linked to user
- 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:
- Note the exact action failing
- Check documentation for required permission
- 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:
-
Document the issue:
- User email/ID
- Exact action attempted
- Exact error message
- Current roles and permissions
-
Check for related:
- Is this one user or multiple?
- Is this one action or multiple?
- When did it start?
-
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