When Folder Permissions Stop Scaling: Attribute-Based Document Authorization with OPA

Folder permissions work well when access follows a stable hierarchy. They become harder to maintain when access also depends on case assignment, document classification, jurisdiction, approval state, and the operation being requested. Copying documents into more folders or creating a group for every combination makes the rules difficult to explain and review.

Attribute-based access control (ABAC) evaluates facts about the requester, document, action, and relevant context. Open Policy Agent (OPA) provides a policy engine for those decisions. The design succeeds when the facts are trustworthy, each delivery path enforces the decision, and a reviewer can explain why access was allowed or denied.

FormKiQ’s point of view: keep roles and refine document access

FormKiQ’s OPA-based authorization can be combined with both role-based access control (RBAC) and folder permissions. Use RBAC for job responsibilities and site access, folder permissions for access to specific document areas, and OPA policies for finer conditions based on document attributes and caller context. For example, a caseworker may need site read access, permission for the case folder, and an OPA decision allowing access to that document’s classification and case assignment.

FormKiQ already implements ABAC through its OPA integration, with global or site-specific policy configuration. The security documentation identifies ABAC support in FormKiQ Advanced and Enterprise. OPA is available through all three FormKiQ APIs: the JWT-authenticated API, the AWS IAM-authenticated API, and the API-key API. Choose the authentication method for the caller, then configure the applicable RBAC, folder permissions, and OPA policies together. Confirm the caller context available to each policy and verify search constraints in the selected deployment.

Define permissions by action

A user may be allowed to read an approved rendition but not retrieve the original. That distinction requires separate controlled delivery paths; a hidden download button cannot enforce it. Map each business action to the actual endpoints and HTTP methods rather than assuming every GET is a harmless read or every POST is an edit.

Make the attributes trustworthy

For every policy input, name the authoritative source, owner, update mechanism, and acceptable age. Validate identity tokens, including issuer, audience, signature, and expiry, before using their claims. Resolve the caller’s permitted site and the document’s site independently; a client-supplied site identifier is a request parameter, not proof of membership.

Load document classification and access attributes from governed state. Protect changes to those fields separately from ordinary content edits. A policy that restricts confidential records provides little protection if the requester can reclassify the same record as public.

Treat missing or malformed facts as validation failures with defined handling. For protected actions, require a valid allow decision; an absent classification should not fall through to a broad role-based allow. A purpose-of-use string typed by the requester is a declaration, not independently verified authority. Device or location conditions also need trusted signals and an enforcement path that actually supplies them.

Separate the policy decision from enforcement

OPA evaluates the input and returns a result. The application or gateway must query the intended decision and enforce it before releasing data or making a change. Define the decision path, input schema, result shape, and behavior for undefined results, errors, timeouts, and unavailable attributes. Deny a protected action when no valid authorization decision is available.

Define prohibitions explicitly, but do not assume naming a rule deny gives it precedence. OPA’s conflict-resolution guidance explains that allow and deny are policy-defined names; the policy author determines how they combine. Test the final decision the FormKiQ integration consumes, including cases where a broad role and a specific restriction both match. Also distinguish raw policy configuration from the policy-item API: the documented policy-item interface currently supports ALLOW items. Do not assume it accepts every rule available in Rego.

Cover console calls, integration APIs, background jobs, previews, public-sharing routes, and direct storage access. OPA is available across JWT, IAM, and API-key access; these authentication methods can supply different caller context and privileges. Map each integration’s identity to the intended authorization rules and test the combined RBAC, folder, and OPA controls on each API path. OPA authorization at an application endpoint does not restrict an independently privileged storage administrator or automatically revoke a previously issued retrieval URL.

Search authorization is a query-design problem

“May this person read this document?” differs from “Which documents may this person search?” Fetching an unrestricted page and removing forbidden rows afterward can expose counts, facets, snippets, or pagination behavior. Build authorization constraints into candidate selection where supported, then check current access again before returning protected content.

OPA’s data-filtering model distinguishes individual decisions from queries that identify permitted resources. The application still has to translate and enforce the resulting constraints. Partial evaluation is not automatic permission to run an unrestricted database search.

For FormKiQ, validate the exact policy shape against the deployed version and search endpoint. Metadata search depends on supported DynamoDB access patterns and configured composite keys; full-text search uses OpenSearch when the module is installed. Complex or changing predicates may be a better fit for OpenSearch, but the authorization translation, counts, aggregations, and paging still need verification. If the backend cannot express a required restriction safely, reject the query or redesign the retrieval path.

Plan for assignment changes and stale decisions

A valid token may still contain an old team or case assignment. Define how quickly assignment removal, classification changes, and policy updates must affect access. Decision caches must distinguish the subject, site, action, resource or version, relevant context, and policy and attribute revisions. A short cache lifetime is useful only if it meets the required withdrawal window.

Long-running exports need checks at execution and release, not only when the request enters a queue. Preserve the initiating user’s authorization context rather than allowing a broadly privileged worker identity to turn every queued request into an authorized export. Recheck relevant state before sensitive writes and define how concurrent changes are handled.

Worked example: reassignment of a sensitive case

1. 1. Establish the permitted scope

   A caseworker has site read access through RBAC, read permission for the case folder, an active assignment to Case C-204, and clearance for its restricted documents. OPA evaluates the applicable document and caller attributes alongside those access layers. Search returns the permitted records; opening a specific version receives a separate current-access check.

2. 2. Request an export

   The user can read the case but lacks bulk-export authority. The export request is denied even though a read request succeeds. Record the business reason without disclosing restricted facts to the caller.

3. 3. Remove the assignment

   A supervisor reassigns the case. Invalidate or age out the relevant authorization state within the agreed window. Test the old session, search filters, cached decisions, previews, and any previously issued retrieval credentials.

4. 4. Explain the outcome

   Correlate the access attempt with the assignment revision, policy revision, decision, and delivery outcome. Distinguish new requests that were denied from credentials or downloaded copies outside that decision’s immediate control.

Deploy and observe policies as production code

Version and review policy changes alongside representative decision fixtures. Test allowed, denied, cross-site, missing, malformed, stale, and conflicting inputs, plus the enforcement adapter’s handling of invalid responses. Pin examples and tests to the Rego version used by the deployed integration. A policy-engine unit test cannot prove that a preview endpoint or export worker enforces its result.

Compare candidate decisions with the active policy before rollout, then verify activation and keep a rollback path. For deployments using OPA bundles, configure and test verification and update behavior deliberately. A healthy process is insufficient if it is serving an outdated policy beyond the accepted freshness window.

Keep a decision identifier, policy revision, subject and resource references, action, result, reason code, and request correlation identifier. OPA decision logging can include policy inputs and results, so configure masking and verify that sensitive claims, credentials, or document contents do not leak into logs. Do not assume every integration enables these logs automatically.

Link the policy decision to the application outcome. An allow decision does not prove content was delivered or a change succeeded. Monitor missing decisions, failed log delivery, outdated policy instances, and repeated denials; keep operational evidence under its own access and retention controls.

Ask for a demonstration across every access path

• Change the requested site or document identifier. Show that valid authentication cannot cross the caller’s permitted boundary.
• Try to lower a classification or assign yourself to a case through ordinary editing APIs. Show that governance permissions prevent it.
• Combine a broad allow with a specific prohibition, then remove a required attribute. Verify the final consumed decision fails safely.
• Repeat the same policy through search, previews, original retrieval, sharing, and queued exports. Measure withdrawal after an assignment change.