Match User Property

The Match User Property (matchUserProperty) access rule is a versatile Attribute-Based Access Control (ABAC) gate. It restricts access based on any attribute attached to the authenticated user’s session (such as department, subscriptionTier, accountStatus, region, or isVerified).

While Match User Role evaluates role hierarchy and RBAC permissions, Match User Property acts as a general-purpose attribute gate that can evaluate any custom string, number, or boolean property with zero database queries.

---

1. How It Works

• Fast Pre-Fetch Evaluation: Evaluates during the PRE_FETCH phase directly from the authenticated user object in memory, without executing additional authorization queries.
• Flexible Comparison Operators: Supports exact matching, set membership (in/notIn), string substring checks (startsWith, contains), and numeric thresholds (>, <, >=, <=).
• Available at All Levels: Can be attached globally at the API Model level (e.g. requiring verified accounts across the whole API), at the Exposed Entity level, or on individual Actions.

Property	Specification
Rule Type	matchUserProperty
Supported Strategies	All strategies (RBAC, OrganizationRBAC, EnterpriseRBAC)
Allowed Placement Levels	Global API Model Level (api), Exposed Entity Level (exposure), Action Level (action)
Execution Phase	PRE_FETCH across all action kinds (list, read, create, update, delete, link, unlink)

---

2. Prerequisites in the Data Domain & Session Configuration

To use Match User Property, the target field must satisfy two requirements:

1. Defined in the Domain Model: The property must exist on the User entity (e.g. department, tier, is_verified, region).
2. Configured in Session Definition Properties: In the API Modeler’s Session Configuration tab, the property must be included in Session Definition Properties.

Session Configuration Requirement

With every authenticated request, the runtime authenticates the session and loads the user record from the database, but only hydrates the specific properties declared in Session Definition Properties. If a property is not included in the session definition, the engine will not load it into the session context, resulting in a 500 Internal Server Error during rule evaluation.

---

3. Supported Comparison Operators

When configuring Match User Property, you select a target property, a comparison operator, and an expected value:

1. Equality & Inequality

• equal (==): The session property must exactly match the static value (string, number, or boolean).
  • Example: status equal 'active', is_verified equal true.
• notEqual (!=): The session property must not match the specified value.
  • Example: account_state notEqual 'suspended'.

2. Set Membership (in & notIn)

• in: The user’s property value must match at least one value in the specified array.
  • Example: tier in ['pro', 'enterprise', 'vip'].
• notIn: The user’s property value must not be present in the specified array.
  • Example: tier notIn ['free_trial', 'banned'].

3. String Pattern Matching

• startsWith: The string starts with the specified prefix (e.g. employee_id startsWith 'ENG-').
• endsWith: The string ends with the specified suffix (e.g. email endsWith '@corp.example.com').
• contains: The string contains the specified substring (e.g. permissions_csv contains 'export').

4. Numeric Comparisons

• greaterThan (>) & greaterThanOrEqual (>=): User value meets or exceeds numeric threshold (e.g. credit_balance >= 50).
• lessThan (<) & lessThanOrEqual (<=): User value is at or below numeric threshold (e.g. strike_count <= 2).

---

4. Recommended Modeling Patterns

Pattern 1: Global Account Status & Email Verification Baseline

Protect your entire API from unverified or suspended users by attaching Match User Property to the global API Model default scenario:

graph LR
    subgraph "Global API Scenario (Evaluated on All Endpoints)"
        Auth["Allow Authenticated"] --> Verified["Match User Property: is_verified == true"]
        Verified --> Active["Match User Property: status == 'active'"]
    end

---

Pattern 2: Feature Gating by Subscription Tier

Restrict premium actions (such as high-volume data export or generative AI workflows) to paid customers:

• On POST /analytics/export:
  • Add scenario: [Allow Authenticated, Match User Property (tier in ['pro', 'enterprise'])].
• Users on the free tier attempting to export receive an immediate 403 Forbidden.

---

Pattern 3: Department-Based Access with Ownership Fallback

For internal corporate tools (such as viewing payroll or HR documents), combine department property matching with resource ownership in separate scenarios:

SalaryRecord.read Scenarios:
├── Scenario 1 (HR Staff & Payroll Managers):
│   └── Match User Property: department == 'hr'      <- HR staff can read all salary records
└── Scenario 2 (Employee Self-Service):
    ├── Allow Authenticated
    └── Match Resource Owner (employee)               <- Employees can only read their own record

---

5. HTTP Status Codes Summary

Caller State	Endpoint Configuration	Resulting HTTP Status
Anonymous (No token)	Endpoint requires Match User Property	401 Unauthorized
Session Property Matches	User’s session attribute satisfies operator criteria (e.g. tier == 'pro')	200 OK / 201 Created
Session Property Fails	User’s session attribute does not satisfy operator criteria (e.g. tier == 'free')	403 Forbidden
Missing Property in Session	Property was not configured in Session Definition Properties	500 Internal Server Error

---

Next Steps

• Match User Role: Role-based access control and privilege tiers.
• Match Resource Attribute: Attribute-based checks against the target record being accessed.
• Session Configuration Guide: How to configure session definition properties in the API Modeler.