Access Caveats Troubleshooting Guide

Overview

This guide helps administrators diagnose and resolve issues related to Access Caveats functionality in Brief Connect. Access Caveats control access to restricted records through field value filtering in Role Assignments.

Common Issues and Solutions

Issue 1: User Cannot Access Restricted Record with Appropriate Caveat

Symptoms: - User should have access based on caveat selection - User gets "Access Denied" or cannot see the record - User is in the correct security group

Diagnostic Steps:

1. Verify Record Configuration:

   Check record settings:
   
   - Override Default Access: Must be "Yes/True"
   - Access Caveats: Verify correct caveats are selected
   

2. Check Role Assignment Configuration:

   Verify Role Assignment has correct ForFieldValues:
   {
     "PartitionKey": "[RecordType or All]",
     "AADGroupNames": "[Correct security group]", 
     "ForFieldValues": "[{\"ABCAccessCaveats\":\"~[CaveatName]\"}]"
   }
   

3. Validate Security Group Membership:

4. Confirm user is member of security group specified in Role Assignment
5. Check for nested group membership if applicable
6. Verify group names match exactly (case-sensitive)

Solutions: - Enable "Override Default Access" on the record - Correct caveat selection on the record - Fix Role Assignment ForFieldValues syntax - Add user to appropriate security group - Wait for group membership sync (can take up to 24 hours)

Issue 2: Unexpected Access Granted to Restricted Record

Symptoms: - Users can access records they shouldn't - Access granted despite not being in caveat-specific groups - Security expectations not met

Diagnostic Steps:

1. Audit All Role Assignments:

   Check for overlapping or overly broad assignments:
   - Multiple Role Assignments for same user/group
   - Broad caveat filters like "~" without specific caveat names
   - Missing field value filters
   

2. Review User's Effective Permissions:

3. Check all security groups user belongs to
4. Identify all Role Assignments that apply to the user

5. Look for admin permissions or override roles

6. Verify Record Setup:

7. Confirm "Override Default Access" is enabled
8. Check if caveats are correctly applied
9. Review security classification alignment

Solutions: - Remove or modify conflicting Role Assignments - Tighten field value filters to be more specific - Remove users from inappropriate security groups - Enable proper record restriction

Issue 3: Access Caveats Field Not Available

Symptoms: - Users cannot see Access Caveats field when creating/editing records - Field appears but is read-only or disabled - Field missing from record forms

Diagnostic Steps:

1. Check Field Configuration:

   Verify in Admin Panel > Configuration:
   - ABCAccessCaveats field is active (isActive: true)
   - Field is enabled for appropriate stages
   - Field type is correctly set (fieldType: 3 for taxonomy)
   

2. Validate Term Store:

3. Verify "Teams" term set exists in SharePoint Term Store
4. Confirm all caveat terms are present (Personnel, Cabinet, Legal, Freedom of Information)

5. Check term permissions and availability

6. Review User Permissions:

7. Confirm user has edit permissions on records
8. Check if user's role allows field modification
9. Verify content type field permissions

Solutions: - Enable ABCAccessCaveats field in Admin Panel configuration - Restore missing terms in SharePoint Term Store - Grant appropriate edit permissions to user - Refresh browser cache and test again

Issue 4: Role Assignment Field Value Filter Syntax Errors

Symptoms: - Role Assignments created but not working - Users not getting expected access - Permission evaluation errors in logs

Common Syntax Errors:

❌ Incorrect:

"ForFieldValues": "ABCAccessCaveats:Personnel"
"ForFieldValues": "[ABCAccessCaveats~Personnel]"  
"ForFieldValues": "{'ABCAccessCaveats':'~Personnel'}"

✅ Correct:

"ForFieldValues": "[{\"ABCAccessCaveats\":\"~Personnel\"}]"
"ForFieldValues": "[{\"ABCAccessCaveats\":\"~Cabinet\"}, {\"ABCAccessCaveats\":\"~Legal\"}]"

Solutions: - Use proper JSON array format with escaped quotes - Include proper comparison operator (~ for contains) - Validate JSON syntax before saving - Test with single caveat first, then add complexity

Issue 5: Performance Issues with Caveat Filtering

Symptoms: - Slow record loading for restricted records - Timeouts when accessing records with caveats - High resource usage during permission evaluation

Diagnostic Steps:

1. Review Role Assignment Complexity:
2. Count number of Role Assignments with field value filters
3. Check for overly complex ForFieldValues expressions

4. Identify assignments with multiple field filters

5. Monitor Permission Evaluation:

6. Check Application Insights logs for performance metrics
7. Look for timeout errors during permission calculation
8. Monitor database query performance

Solutions: - Simplify complex Role Assignments where possible
- Reduce number of field value filters per assignment - Optimize security group membership (fewer, larger groups vs many small groups) - Consider caching strategies for frequently accessed records

Diagnostic Tools and Techniques

Role Assignment Validation

Use this checklist to validate Role Assignment configuration:

{
  "PartitionKey": "All",                    // ✓ Correct partition key
  "RowKey": "Descriptive Name",            // ✓ Unique, descriptive name  
  "AADGroupNames": "SG-Group-Name",        // ✓ Exact group name
  "PermissionSet": "StandardUser",         // ✓ Valid permission set
  "ForFieldValues": "[{\"ABCAccessCaveats\":\"~Personnel\"}]", // ✓ Valid JSON
  "Organisations": "All",                  // ✓ Organization scope
  "Stages": "All"                         // ✓ Stage scope
}

Testing Access Scenarios

Create test scenarios to validate caveat functionality:

1. Test User Setup:
2. Create test user accounts in different security groups

3. Test with users who should and shouldn't have access

4. Test Record Creation:

   Scenario 1: Personnel Caveat
   - Override Default Access: Yes
   - Access Caveats: Personnel
   - Expected: Only Personnel group members can access
   
   Scenario 2: Multi-Caveat
   - Override Default Access: Yes  
   - Access Caveats: Legal, Cabinet
   - Expected: Legal OR Cabinet group members can access
   
   Scenario 3: No Restriction
   - Override Default Access: No
   - Access Caveats: Personnel
   - Expected: Normal role permissions apply (caveats ignored)
   

Log Analysis

Key log entries to monitor:

Application Insights Queries:

// Permission evaluation errors
traces
| where message contains "FieldValuesMatch"
| where severityLevel >= 2

// Role assignment processing
traces  
| where message contains "GetPermissionPairs"
| project timestamp, message, severityLevel

// Access denied events
traces
| where message contains "Access Denied"
| where customDimensions contains "caveat"

Advanced Troubleshooting

Permission Flow Analysis

To understand why a user can/cannot access a record:

1. Identify User's Groups:

   User Groups → Role Assignments → Field Filters → Record Match
   

2. Trace Permission Evaluation:

3. Stage filtering (record stage vs role assignment stages)
4. Organization filtering (record org vs role assignment orgs)

5. Field value filtering (record caveats vs role assignment filters)

6. Check Permission Inheritance:

7. User-specific role assignments
8. Group-based role assignments
9. Admin overrides

Database Query Troubleshooting

If experiencing performance issues:

1. Check Table Storage Performance:
2. Monitor Role Assignment table query times
3. Look for partition hot spots

4. Verify proper indexing

5. Optimize Role Assignments:

6. Consolidate similar assignments
7. Use broader partition keys where appropriate
8. Minimize complex field value filters

Integration Issues

SharePoint Term Store: - Verify Term Store service application is running - Check term permissions and inheritance - Test term retrieval via SharePoint API

Azure AD Groups: - Confirm group synchronization is working - Test group membership queries via Microsoft Graph - Verify nested group expansion

Prevention Strategies

Configuration Management

1. Standardize Role Assignments:
2. Use consistent naming conventions
3. Document purpose and scope of each assignment

4. Regular review and cleanup

5. Testing Process:

6. Test all caveat combinations before production
7. Maintain test user accounts for each security group

8. Automated testing of permission scenarios

9. Documentation:

10. Keep current mapping of groups to caveats
11. Document business rules for caveat usage
12. Maintain troubleshooting runbooks

Monitoring and Alerting

Set up monitoring for: - Failed permission evaluations - Unexpected access patterns
- Role assignment configuration changes - Security group membership changes

Escalation Procedures

When to Escalate

Escalate to development team when: - Core permission logic appears faulty - Performance issues cannot be resolved through configuration - Data corruption in Role Assignments table - Integration failures with Azure AD or SharePoint

Information to Provide

When escalating, include: - Specific user accounts and records affected - Role Assignment configurations
- Error messages and logs - Steps to reproduce the issue - Business impact and urgency

Temporary Workarounds

While waiting for resolution: - Temporarily add users to broader security groups - Use admin override permissions for critical access needs - Document temporary changes for later cleanup - Communicate impact to affected users

Related Resources

• Access Caveats Configuration
• Filtering by Field Values in Role Assignments
• Background Permissions Management