Permissions: Rule Bases, SecurityURIHeader, and SecurityURIBody

integration / exchange / create

integration / workflow / create

system / action-enablement / check

A scoped action is the atomic framework-level unit.

A capability is an application-defined composition over one or more scoped actions.

Settings, feature flags, and runtime prerequisites are attached to the scoped action requirement manifest.

allowed=false usually means a policy or role problem

enabled=false usually means a feature flag or administrative rollout problem

ready=false usually means setup, configuration, or runtime dependencies are incomplete

impact: one of ALLOWED, ENABLED, or READY

type: the dependency type, such as permission or feature-flag

code: a stable blocker code, such as permission-denied

message: a human-readable explanation

severity: typically warn or error

metadata: additional structured context

POST /system/actions/enablement/check

GET /system/actions/enablement/manifest

area=system

functionalDomain=action-enablement

action=check|view

which scoped action is being described

which dependencies must be satisfied for that action to be usable

optional display-oriented metadata such as displayName and description

action integration / guided_integration / create depends on feature flag guided-integrations

action integration / exchange / create depends on a tenant filesystem being provisioned

action system / some-admin-action / save depends on a specific config property being present

identity

realm

roles

scope

DataDomain

the target ScopedActionRef

permission-denied

feature-flag-missing

feature-flag-disabled

setting-name-missing

setting-missing

entity-model-unresolved

entity-missing

evaluation falls back to a synthetic requirement that checks permission

the response also includes a manifest-missing blocker with impact=READY

the response includes unsupported-dependency-type

the blocker is attached with impact=READY

fillUIActions() still answers what actions are allowed from the permission perspective

scoped action enablement answers why an action should still be disabled or annotated in the UI

setup dashboards

onboarding flows

context-sensitive "why unavailable?" messaging

shells or MCP clients that need structured blockers

managed-secret-configured

tenant-filesystem-provisioned

standard-mounts-present

workflow-runtime-reachable

has the tenant filesystem been provisioned?

do the standard mounts exist?

is a required managed secret configured?

is the workflow runtime reachable?

Keep permission checks canonical. Do not duplicate authorization logic inside custom readiness resolvers.

Use feature-flag dependencies for rollout state, not for durable authorization.

Use setting-present and entity-exists only for generic prerequisites. Domain-heavy operational checks belong in application or enterprise resolvers.

Keep blocker codes stable because UIs and automation may key off them.

Treat capabilities as documentation and UX groupings over scoped actions, not as a substitute for area / functionalDomain / action.

Roles from the identity provider (JWT/SecurityIdentity)

Roles configured on the user record (CredentialUserIdPassword.roles)

Identity Provider (JWT): roles commonly arrive via standard claims (for example, groups, roles, or provider-specific fields). Quarkus maps these into SecurityIdentity.getRoles(). In multi-realm setups, the realm in X-Realm can scope lookups but does not alter what the JWT asserts.

Quantum user record: com.e2eq.framework.model.security.CredentialUserIdPassword has a String[] roles field stored per realm. This can be administered by Quantum to grant platform- or tenant-level roles.

Union: the effective role set is the union of JWT roles and CredentialUserIdPassword.roles. If either source is empty, the other source defines the set.

Fallback: when neither source yields roles, the framework defaults to ANONYMOUS.

Where implemented: SecurityFilter.determinePrincipalContext builds PrincipalContext with the merged roles.

The user record is looked up by subject or userId in the active realm (default or X-Realm). If a realm override is provided, it is validated with CredentialUserIdPassword.realmRegEx.

Roles stored in a user record are realm-specific; JWT roles are whatever the IdP asserts for the token.

Quantum-managed roles:

IdP-managed roles:

Hybrid (recommended in many deployments):

JWT-only:

Quantum-only:

Hybrid union:

Keep role names stable and environment-agnostic; use realms/permissions to scope where needed.

Avoid overloading roles for feature rollout; use Feature Flags for rollout and variants, and roles for durable authorization.

When IdP is authoritative, ensure consistent claim mapping so SecurityIdentity.getRoles() contains the expected values; commonly via groups claim in JWT.

Use grant-based permission rules and require the minimal set of roles (rolesAny/rolesAll) needed for each capability.

User model: com.e2eq.framework.model.security.CredentialUserIdPassword.roles

Context: com.e2eq.framework.model.securityrules.PrincipalContext.getRoles()

Filter logic: com.e2eq.framework.rest.filters.SecurityFilter.determinePrincipalContext

name, description

securityURI.header: identity, area, functionalDomain, action (supports wildcard "*")

securityURI.body: realm, orgRefName, accountNumber, tenantId, ownerId, dataSegment, resourceId (supports wildcard "*")

effect: ALLOW or DENY

priority: integer; lower numbers evaluated first

finalRule: boolean; stop evaluating when this rule applies

andFilterString / orFilterString: ANTLR filter DSL snippets injected into repository queries (see Query Language section)

joinOp: how to combine the andFilterString group with the orFilterString group when both are present; defaults to AND

andFilterString: a filter expression added to the AND group.

orFilterString: a filter expression added to the OR group.

joinOp: when both groups are present, specifies how to join them. Values: AND or OR. Default: AND.

AND only

OR only

AND + OR with joinOp: AND (default)

AND + OR with joinOp: OR

The filter DSL is described in the Query Language guide; it maps to Morphia dev.morphia.query.filters.Filters under the hood via MorphiaUtils.convertToFilter.

SPI: com.e2eq.framework.securityrules.AccessListResolver

key(): the variable name published to the filter variable bundle (e.g., "accessibleCustomerIds").

supports(pctx, rctx, modelClass): return true when this resolver applies for the current request and repository model type.

resolve(pctx, rctx, modelClass): return a Collection<?> which will be available as ${<key>} in filter strings.

RuleContext.getFilters discovers all AccessListResolver beans via CDI, calls supports(…​), and for those that apply it puts key() → resolve(…​) into the "extraObjects" map. MorphiaUtils.buildVariableBundle merges these into the variable set used by convertToFilter.

In your filter DSL, use:

IN with resolver-provided lists: field:^${key}

Equality with resolver-provided scalars: field:${key}

You can also reference nested principals: ${pcontext.dataDomain.tenantId}, ${principalId}, etc.

Restrict Orders to the set of ids returned by a resolver

Use resolver that returns customer codes and OR with a public segment

Associate/Sales Rep binding: Link a UserProfile to an Associate entity and expose associateId for filtering

Territory assignments: Expose accessibleTerritoryIds based on the user’s role assignments

Organizational hierarchies: Expose accessibleLocationIds via ontology relationships

Custom attributes: Any domain-specific property needed for security filtering

SPI: com.e2eq.framework.model.securityrules.PrincipalContextPropertiesResolver

priority(): Execution order (lower = earlier). Default: 1000.

resolve(ResolutionContext): Return a Map<String, Object> of properties to add to PrincipalContext.

ResolutionContext provides access to:

isAnonymous(), getPrincipalName(), getIdentityRoles(): Security identity info

getUserId(), getSubjectId(): User identifiers

getRealm(), getDataDomain(), getDomainContext(): Realm and domain context

getHeader(name): HTTP request headers

getJwtClaim(name): JWT token claims

hasCredentials(), getCredentialUserId(), getCredentialRoles(): Database credentials

SecurityFilter discovers all resolvers via CDI, invokes them in priority order, and merges results into PrincipalContext.customProperties.

MorphiaUtils.createStandardVariableMapFrom includes custom properties, making them available as ${key} in filter strings.

Use PrincipalContextPropertiesResolver for properties that apply to the user regardless of what resource they’re accessing (e.g., associate ID, territory assignments).

Use AccessListResolver when the access list depends on the specific resource type or action being performed.

Both mechanisms can coexist and complement each other.

Return empty maps (not null) from resolvers; resolver failures are logged and skipped, not propagated.

Properties should not override built-in PrincipalContext fields (userId, roles, etc.).

getList / getListByQuery / find: RuleContext.getFilters augments the base filters with the effective security filters before executing the query.

count: same as read paths, ensuring counts reflect scoped visibility.

save (create): rules typically do not inject filters for inserts; writes are validated by separate preconditions or postconditionScript. If your policy encodes write-scope, author UPDATE/DELETE rules to guard modifications rather than CREATE, unless your domain enforces ownership/tenant on insert.

update / merge / set / bulk set: the security filters are ANDed into the target selection so only documents visible under the policy are affected.

delete (by id or by query): security filters are applied to the selection to prevent deleting outside the allowed scope.

Filters are applied regardless of whether the match decision was ALLOW or DENY; only ALLOW rules contribute filters. DENY rules decide the outcome but do not add filters.

finalRule: true stops evaluating later rules for both decision and filter contribution.

If no ALLOW rules match, repositories may still execute with caller-provided filters, but upstream permission checks should have DENIED the action; by convention, most endpoints call checkRules and short-circuit DENY before hitting the database.

save: no security filters are injected into the insert operation; enforce ownership/tenant fields via model validation and/or postconditionScript.

find/findById: adds security filters; if the requested id is outside scope, the result is empty.

getList/getListByQuery: adds security filters to user-supplied query; scope cannot be broadened by the client.

update/merge: AND the security filters into the update selector; records outside scope are unaffected.

delete: AND the security filters into the delete selector; out-of-scope records are not removed.

GET /list

GET /id/{id} and GET /id?id=…​

GET /refName/{refName} and GET /refName?refName=…​

GET /count?filter=…​

GET /schema

POST /

PUT /set?id=…​&pairs=field:value

PUT /bulk/setByQuery?filter=…​&pairs=…​

PUT /bulk/setByIds

PUT /bulk/setByRefAndDomain

DELETE /id/{id} (or /id?id=…​)

DELETE /refName/{refName} (or /refName?refName=…​)

CSV import/export endpoints for bulk operations:

Index management (admin only):

Authorization: Bearer <token>

X-Realm: realm identifier (optional but recommended in multi-tenant deployments)

filter uses the ANTLR-based DSL (see REST CRUD > Query Language)

sort uses comma-separated fields with optional +/- prefix; projection accepts a comma-separated field list

Create or update a Policy

List policies for principalId=user

Delete a policy by refName

Persistence vs. in-memory rules:

PolicyResource updates the persistent store of policies (one policy per principalId or role with a list of rules).

RuleContext is the in-memory evaluator used by repositories and resources to enforce permissions. It matches SecurityURIHeader/Body, orders rules by priority, and applies effects and filters.

Making persisted policy changes effective:

On startup, migrations (see InitializeDatabase and AddAnonymousSecurityRules) typically seed default policies and/or programmatically add rules to RuleContext.

When you modify policies via REST, you have two options to apply them at runtime:

Tip: If you maintain a background watcher or admin endpoint to refresh policies, keep it tenant/realm-aware and idempotent.

Evaluation semantics (recap):

Rules are sorted by ascending priority; the first decisive rule sets the outcome. finalRule=true stops further processing.

andFilterString/orFilterString contribute repository filters through RuleContext.getFilters(), constraining result sets and write scopes.

principalId can be a concrete userId or a role; RuleContext considers both the principal and all associated roles.

Safe rollout:

Create new policies with a higher numeric priority (lower precedence) first, test with GET /schema and dry-run queries.

Use realm scoping via X-Realm to stage changes in a non-production realm.

Prefer DENY with low priority numbers for critical protections.

X-Realm: Overrides the target realm (MongoDB database) used by repositories for this request. Your own identity and roles remain the same. The DataDomain is updated to the target realm’s default DomainContext (while preserving your userId as the ownerId). This ensures that data created via X-Realm is properly scoped to the target realm’s tenant/org structure.

X-Impersonate-Subject or X-Impersonate-UserId: Causes the request to run as another identity. The effective permissions become those of the impersonated identity (potentially more or less than your own). This is analogous to sudo on Unix or to "simulate a user/role" for troubleshooting.

X-Acting-On-Behalf-Of-Subject or X-Acting-On-Behalf-Of-UserId: Records that the caller is acting on behalf of another party (for audit/tracking purposes). Unlike impersonation, this does NOT change permissions—the caller retains their own identity and roles.

Rule matching and effects (ALLOW/DENY) still follow the standard algorithm described earlier.

With X-Realm (no impersonation):

The PrincipalContext.defaultRealm is set to the header value (after validation), and repositories operate in that realm.

The DataDomain is updated from the target realm’s DomainContext (org, tenant, account, dataSegment), while preserving your userId as the ownerId.

Your own roles and identity remain intact; the rule base is evaluated for your identity and roles but with the target realm’s data context.

Permission filter strings can use ${defaultRealm} to dynamically scope queries based on the active realm.

With impersonation:

The PrincipalContext is rebuilt from the impersonated user’s credential. The effective roles used by the rule engine include the impersonated user’s roles; the platform also merges in the caller’s security roles from Quarkus SecurityIdentity. This means permissions can be a superset; design policy rules accordingly.

The effective realm for the request is set to the impersonated user’s default realm (not the X-Realm header). If you passed X-Realm, it is still validated (see below) but not used to override the impersonated default realm in the current implementation.

The DataDomain is set from the impersonated user’s DomainContext.

With Acting-On-Behalf-Of:

The caller retains their own identity, roles, realm, and DataDomain.

The X-Acting-On-Behalf-Of-Subject or X-Acting-On-Behalf-Of-UserId is recorded in the PrincipalContext for audit purposes.

This is useful for service-to-service calls or when a support agent needs to perform actions that should be attributed to a customer.

realmRegEx (for X-Realm):

A wildcard pattern ("*" matches any sequence; case-insensitive) listing the realms a user is allowed to target with X-Realm.

If X-Realm is present but realmRegEx is null/blank or does not match the requested realm, the server returns 403 Forbidden.

Examples:

"*" → allow any realm

"acme-*" → allow realms that start with acme-

"dev|stage|prod" is not supported as-is; use wildcards like "dev*" and "stage*" or a combined pattern like "(dev|stage|prod)" only if you store a true regex. The current validator replaces '' with "." and matches case-insensitively.

impersonateFilterScript (for X-Impersonate-*):

A JavaScript snippet executed by the server (GraalVM) that must return a boolean. It receives three variables: username (the caller’s subject), userId (caller’s userId), and realm (the requested realm or current DB name).

If the script evaluates to false, the server returns 403 Forbidden for impersonation.

If the script is missing (null) and you attempt impersonation, the server rejects the request with 400/IllegalArgumentException.

Realm override (X-Realm):

Who you are does not change; only where you act changes. Your permissions (as determined by policies attached to your identity/roles) are applied against data in the specified realm.

DataDomain changes: The DataDomain is updated from the target realm’s DomainContext (tenant, org, account), ensuring new records are created with the correct scoping.

Use cases:

Multi-tenant admin tooling that needs to inspect or repair data in customer realms.

Reporting or backfills where the same service is pointed at different tenant databases per request.

Creating data in a target realm with proper DataDomain stamping.

Impersonation (X-Impersonate-*):

Who you are (for authorization purposes) changes. You act with the impersonated identity’s permissions; depending on your configuration, additional caller roles may be merged.

The DataDomain is set from the impersonated user’s credential.

Use cases:

Temporary elevation to an admin identity (sudo-like) for break-glass operations.

Simulate what a given role/identity can see/do for troubleshooting or customer support.

Testing user-specific permission rules without logging in as that user.

Acting-On-Behalf-Of (X-Acting-On-Behalf-Of-*):

Who you are does NOT change; you retain your own identity, roles, realm, and DataDomain.

The "acting on behalf of" information is recorded in the PrincipalContext for audit trails.

Use cases:

Service-to-service calls where the downstream service needs to know the original requestor.

Support agents performing actions that should be audited as being done "on behalf of" a customer.

Compliance and audit requirements where the chain of delegation must be recorded.

List policies in a different realm using your own identity

Simulate another user by subject while staying in their default realm

Attempt impersonation with a realm hint (validated by script; effective realm = impersonated default)

Start with no policy and verify your default flows. Add entries only where necessary.

Prefer specific keys (area:domain) for clarity; use wildcards sparingly.

Keep FIXED DataDomain objects minimal and valid for your deployment (orgRefName, tenantId, and dataSegment as needed).

Document any global policy so teams know which areas are centralized.

CredentialUserIdPassword.dataDomainPolicy: optional per‑credential overrides (propagated to PrincipalContext).

GlobalDataDomainPolicyProvider: holds an optional in‑memory global policy (null by default).

DataDomainPolicyEntry.resolutionMode: FROM_CREDENTIAL (default) or FIXED.

DataDomainResolver / DefaultDataDomainResolver: the extension point and default behavior.

Materialize edges in Mongo using OntologyMaterializer (e.g., placedInOrg, orderShipsToRegion).

During rule evaluation, translate a semantic constraint like "has edge placedInOrg to OrgX" into a set of IDs, and combine that with your query.

Preferred: author a rule with a semantic hint and let the application translate it via ListQueryRewriter.

Minimal change path: publish a variable via an AccessListResolver and use an IN filter over _id.

Add an AccessListResolver that returns order IDs for which (tenantId, p="placedInOrg", dst=orgRefName) exists.

In your rule’s AND filter string (query language), use: id:^${idsByPlacedInOrg}

Ontology overview and examples: Ontologies in Quantum

Integration with Morphia and multi-tenancy: Integrating Ontology

Ontology is optional. Enable it per service when the config flag and dependencies are present.

Always scope edge queries by tenantId sourced from RuleContext.

Index edges on (tenantId, p, dst) and (tenantId, src, p) for performance.

LabelResolver (SPI):

public interface LabelResolver {
  boolean supports(Class<?> type);
  java.util.Set<String> resolveLabels(Object entity);
}

DefaultLabelResolver (built-in): Applies to UnversionedBaseModel.

Collects tags (String[]), advancedTags.name, and optionally any dynamicAttributes whose isInheritable()==true, using best‑effort reflection.

LabelService: Aggregates all LabelResolver beans via CDI and delegates to the first that supports the entity type. Also supports annotation-based extraction (see below).

Annotations (optional, opt-in at your model):

@LabelSource(method = "computeLabels") // class-level method returning Collection<String>, String[], or String
public class MyEntity { ... }

public class MyEntity {
  @LabelField                // field can be Collection<String>, String[], or String
  private java.util.List<String> policyLabels;
}

hasLabel(label: String) → Boolean

Returns true if the current resource context has the specified label.

Label resolution uses LabelService (including custom resolvers and annotations) at evaluation time.

Add a new resolver:

@jakarta.enterprise.context.ApplicationScoped
public class InvoiceLabelResolver implements LabelResolver {
  public boolean supports(Class<?> type) { return type.getName().endsWith("Invoice"); }
  public java.util.Set<String> resolveLabels(Object entity) {
    var out = new java.util.LinkedHashSet<String>();
    var inv = (com.example.Invoice) entity;
    if (inv.isHighValue()) out.add("HIGH_VALUE");
    if (inv.isPastDue()) out.add("PAST_DUE");
    return out;
  }
}

Or annotate your model with @LabelSource/@LabelField to contribute labels without writing a resolver.