Skip to content
AI Engineer Guide.

concept · concepts · intermediate · concept 54 of 57

ACL-aware RAG

0 of 57 complete

Why it matters

An index built from every document collapses the source system's permission boundaries into one searchable pool. If a query can reach a document the user cannot open, the answer can reveal it through paraphrase, citation or a summarised figure. Enforcing access requires identity propagation from the request into the retrieval filter, and a synchronisation path that removes access as fast as the source does.

Mental model

Access control is a reading room where each visitor is handed only the folders their badge opens. The metaphor breaks because the librarian also writes a summary, and a summary can mention a folder the visitor was never allowed to see.

How it works

Eight candidates, three deniedInteractive

Synthetic scoped retrieval · tenant acme

Eight candidates · one scope · k 3

bounding boxes

Step 1/6 · Identity into the call

Step 1Identity into the call

The authenticated user and their scope travel with the request. A prompt cannot carry identity, so a route that forgets the scope has to fail rather than search everything.

RETRIEVAL · ACCESS-SCOPED · USER u-8841 · TENANT ACME

, running header, region 1. Select to inspect.

The filter is part of the query

, title, region 2. Select to inspect.
Useru-8841
, form field User, region 3. Select to inspect.
Scope42 principals
, form field Scope, region 4. Select to inspect.
k3
, form field k, region 5. Select to inspect.
Query

Q: what is the enterprise refund window? · one scope · k 3

, paragraph Query, region 6. Select to inspect.
CANDIDATES
#DocACL groupEligible
1d-118supportyes
2d-231legalno
3d-305financeno
4d-204supportyes
5d-244supportyes
6d-318supportyes
7d-402legalno
8d-517supportyes
, table CANDIDATES, region 7. Select to inspect.
In-query filter3 of 3 returned
, form field In-query filter, region 8. Select to inspect.
Post-filter1 of 3 returned
, form field Post-filter, region 9. Select to inspect.
Cachekey: user + scope · 42 principals · shared answers 0
, form field Cache, region 10. Select to inspect.
REVOCATION
EventTimeState
revoke u-441709:02done
index delete09:02done
cache purge09:03done
query as u-441709:040 hits
, table REVOCATION, region 11. Select to inspect.
Citationd-231 denied at resolve · 0 opened
, form field Citation, region 12. Select to inspect.

8 candidates · 3 denied · 5 eligible · k 3 · 3 returned · 0 leaked

, running footer, region 13. Select to inspect.
13 regions

Step record

Identity
u-8841
Scope
42 principals
In prompt
no

The text version summarises this figure; select a region for its full text.

Figure. One scoped retrieval: eight candidates by similarity, three outside the permission scope and five eligible. Filtering inside the query returns three of k = 3; filtering the top three afterwards returns one, because two of them were denied. The revocation record shows the index and the cache both cleared before the next query.

What to notice. Synthetic corpus and permission model. Candidate ids, the scope size, times and hit counts are authored. The figure shows where the scope predicate applies and what a revocation has to reach, not a real ACL implementation or a measured leak rate.

Text version

An access-scoped retrieval record for user u-8841 in tenant acme, with a scope of 42 principals and k of 3. The query asks for the enterprise refund window over the top eight candidates. A candidate table lists d-118, d-231, d-305, d-204, d-244, d-318, d-402 and d-517 with their ACL groups; support documents are eligible and legal and finance documents are denied, giving five eligible and three denied. Two result fields report three of three returned when the filter is inside the query and one of three when the top three are post-filtered. A cache field keys entries by user and scope. A revocation table records a revoke at 09:02, an index delete at 09:02, a cache purge at 09:03 and a query at 09:04 returning zero hits. A citation field records that d-231 was denied at resolve time. Steps mark identity, the candidate set, the in-query filter, the post-filter shortfall, the cache key and the revocation.

  1. Propagate the authenticated user or service identity into the retrieval call, never relying on the prompt to carry it.
  2. Model permissions as filterable metadata on every chunk, derived from the source at ingest and on permission change.
  3. Apply the permission predicate inside the search query so ineligible vectors are never candidates.
  4. Cache by identity or permission set, since a shared answer cache can serve one user's content to another.
  5. Propagate revocations and moves with the same latency target as content updates, and test that a revoked document disappears.
  6. Include the permission check in citation resolution, so a link cannot open a document the reader may not see.

Trade-offs

ChoiceGood forCostFails when
Chunk-level ACLPrecise enforcementLarge metadata and filter costPermission sets are complex and change constantly
Document-level ACLSimpler and smallerOver-restricts when a document has mixed sectionsSections have different audiences
Per-tenant indexStrong isolationMany indexes to operateTenants are numerous or share content
Post-filter in application codeNo engine changesFewer than k results and leak risk in logsPermissions are selective
Trade-off mapInteractive

Good for

Precise enforcement

Cost

Large metadata and filter cost

Fails when

Permission sets are complex and change constantly

  1. Permission sets are complex and change constantly
  2. Sections have different audiences
  3. Tenants are numerous or share content
  4. Permissions are selective

Figure. Each choice with what it buys, what it costs, and the case where it loses.

What to notice. The fourth column is the decision: if the losing case describes your situation, the choice is wrong.

Text version

Four trade-offs: Chunk-level ACL is good for Precise enforcement, costs Large metadata and filter cost, and fails when Permission sets are complex and change constantly. Document-level ACL is good for Simpler and smaller, costs Over-restricts when a document has mixed sections, and fails when Sections have different audiences. Per-tenant index is good for Strong isolation, costs Many indexes to operate, and fails when Tenants are numerous or share content. Post-filter in application code is good for No engine changes, costs Fewer than k results and leak risk in logs, and fails when Permissions are selective

Failure modes

  • Permission filter omitted on a new route. A new endpoint calls the retriever without identity and returns everything. Debug: assert that every retrieval call carries a non-empty permission scope and fail closed when it does not.
  • Stale permissions. A user who lost access still receives answers from the document. Debug: revoke access in the source, wait one sync interval, then query as that user and confirm zero hits.
  • Cache leak across users. A semantic cache returns an answer generated for a user with broader access. Debug: key cache entries by permission set and test with two identities asking the same question.

In production

Log the permission scope and eligible-document count per query, and alert when a scope matches zero documents unexpectedly. Run a periodic access test with synthetic users at different permission levels.

Common misconceptions

People think: Telling the model not to reveal restricted content is access control.

Actually: Instructions are not enforcement; the restricted text must never enter the prompt.

People think: Filtering the final answer is sufficient.

Actually: The passage already shaped the answer, and paraphrase can leak it without any citation.

Interview angle

Put identity into the retrieval filter, treat revocation as a data-freshness problem, and mention cache keying. Name leakage through summaries as the subtle case. Saying the prompt instructs the model to respect permissions is the answer that confuses instruction with enforcement.

Sources