Permission-aware retrieval-augmented generation (RAG) means the retrieval layer decides what a caller may see before any chunk reaches the model. The mechanism is a metadata filter applied at query time against permission fields stored alongside each chunk’s text and vector. If that filter is missing, no amount of prompt instruction will contain the data: AWS’s security guidance treats large language models as untrusted entities and advises assuming that anything placed in a prompt can be returned to the principal who triggered it (AWS Security Blog).
This guide is for practitioners who already have a working RAG pipeline — cloud or self-hosted — and now need to stop users from retrieving documents they are not entitled to. It covers the permission data model, the query-time enforcement point, a concrete implementation sequence, and the failure modes that show up once real users arrive.
Why the filter belongs in the retrieval layer
Authorization is not a model capability. An LLM has no way to know which of the chunks in its context window the current user is allowed to read, and it has no reliable mechanism to withhold one while summarizing the rest. The AWS guidance is explicit that LLMs should be considered untrusted and that any data passed to them as part of a prompt could be returned to the principal. The corollary for RAG is straightforward: restricted content must never enter the context window in the first place.
That leaves the retrieval layer as the enforcement point. The same AWS post notes that capabilities such as vector database metadata filters and syncing identity information between the data source and the knowledge base provide a useful baseline filtering capability, while cautioning that filtering alone is not the whole authorization story — decisions should be tied to the principal’s verified identity, and where tools are involved, identity tokens can be passed to the tool so it can determine what the principal is permitted to access. In practice this means the filter is necessary but should sit inside a larger design where the data source remains the authority on who may see what.
The three components every implementation needs
- A verified caller identity. User ID plus group memberships or roles, resolved from a trusted source such as a signed token validated at your API boundary — never from a field the client can set.
- Permission metadata on every retrievable unit. Each chunk, or each parent document referenced by chunks, carries the identifiers of the users and groups allowed to see it, in a field the engine can filter on.
- A query-time predicate built from the identity and matched against the metadata. If the predicate cannot be built — missing token, unknown user, empty group list — the query must fail closed and return nothing.
Modeling permission metadata
The most common shape is a per-chunk allow list: an array or delimited string of user IDs, an array of group IDs, and optionally a scope identifier that ties the chunk back to a container or workspace. Azure AI Search documents a related constraint that applies broadly: permission metadata must live in filterable string fields. Its query-time access control feature also illustrates an important design choice — with that feature, you do not write the permission filter yourself in the query; the search engine builds a filter internally to exclude unauthorized content (Microsoft Learn).
Where the metadata comes from depends on your data source. Azure AI Search indexers can pull permission metadata automatically for sources with built-in access models, specifically Azure Data Lake Storage (ADLS) Gen2 and SharePoint in Microsoft 365. For other sources, you must assemble the document payload yourself so that it contains both the content and the associated permission metadata, then load the index through the push APIs. The accepted metadata formats there are POSIX-style permissions that identify the level of access plus the group or user ID, or the resource ID of the ADLS Gen2 container when RBAC scope is used.
Two modeling decisions matter more than the field names:
- Granularity. If a single source document mixes permissions — a shared report with a confidential appendix, for example — chunk-level ACLs must reflect that split, or you must inherit the strictest ACL across the whole document. Applying the loosest ACL to a mixed-permission document is a leak.
- Stable identifiers. Store group and user IDs, not display names or email addresses that change. Resolve the caller’s memberships to the same identifier space at query time.
An implementation sequence
The following steps describe a generic pipeline. They are an illustrative design, not a configuration that has been tested here; the exact API calls depend on your vector store or search engine.
Step 1: Capture identity at the API boundary
Validate the caller’s token server-side and extract a user ID plus group or role claims. Do not accept a user identifier supplied in the request body, and do not let the client choose which groups it belongs to. Expected result: every retrieval request carries a server-derived identity object before it reaches the retriever.
Step 2: Resolve memberships to index-compatible identifiers
Directory group claims and index group IDs are often different namespaces. Maintain a mapping, and decide how you handle users with very large group memberships — some engines and token formats impose limits on the number of values in a filter or claim set.
Step 3: Enrich chunks at index time
During ingestion, attach the permission fields to each chunk. If you use a managed indexer with a built-in access model, this may be automatic; otherwise it is your responsibility to assemble the payload with both content and permission metadata.
Step 4: Build the predicate at query time
The retriever constructs a predicate from the resolved identity and applies it to the same query that performs vector or keyword search. A pseudocode sketch of the intent:
# Pseudocode only. Field names and syntax depend on your engine;
# this is not a tested query and is not valid syntax for any specific product.
allowed_users CONTAINS caller.user_id
OR allowed_groups INTERSECTS caller.group_ids
If your platform offers a managed permission-aware search feature, prefer it over hand-rolled predicates, because the engine handles filter construction. Note that Azure AI Search’s query-time ACL and RBAC enforcement is currently a preview feature: Microsoft states that preview capabilities are not covered by a service-level agreement, are not recommended for production workloads, and may change before general availability.
Step 5: Make the failure mode closed
Write the code so that a missing identity, an empty group list, or an error while building the predicate produces zero results rather than an unfiltered query. The dangerous pattern is a conditional that applies the filter when identity is present and silently skips it when it is not.
Step 6: Verify with two identities
Run the identical query as an authorized user and as an unauthorized user. The unauthorized run must return zero matching chunks, not merely fewer. Then test the no-token case and confirm it also returns zero.
Limits, staleness, and operational tradeoffs
Permission-aware RAG adds moving parts, and each one can fail quietly.
- Staleness. When a user is removed from a group, the index still says otherwise until the next sync. Document your re-sync interval and decide whether permission changes should trigger immediate re-indexing or a revocation list checked at query time.
- Filter size. Users in hundreds of groups produce large predicates. Engines differ in how they handle this; test with your heaviest user, not an average one.
- Re-indexing cost. Changing the permission schema usually means rebuilding the index, which is expensive for large corpora. Get the field design right early.
- Baseline versus complete. Metadata filtering is a strong control at the retrieval boundary, but the AWS guidance frames it as a baseline rather than a substitute for authorization decisions anchored to the principal’s identity and the source system.
- Preview status. Managed enforcement features may be preview-only, which affects whether you can rely on them for compliance-driven workloads.
Verification and audit practices
Beyond the two-identity test, a few habits catch leaks early:
- Insert a canary chunk visible only to one group, then query for its unique string as a different group. Any hit is a defect.
- Log the principal and the constructed predicate for each retrieval, so an incident review can reconstruct what was searched. Never log raw tokens.
- Add a unit test that asserts the unfiltered query path does not exist in the retrieval code.
- Re-run the canary test after every change to ingestion, chunking, or the index schema, since those are the changes most likely to drop permission fields.
Notes for local and self-hosted stacks
Self-hosted vector databases and local model runtimes do not provide managed permission ingestion, so the identity mapping and the predicate are entirely yours. On a single-user desktop setup the multi-tenant boundary may not exist, and the relevant risk is a shared machine or an exposed local API. As soon as a local RAG endpoint serves more than one person, the filter must be applied inside the retriever — hiding results in the interface is not a control, because the index remains queryable.
If your corpus is WordPress content, the natural permission signals are already present: post status, password protection, and the role and capability checks that govern who can read a page. Map those into chunk metadata during ingestion and re-sync when visibility changes. Do not treat a theme-level or plugin-level display restriction as sufficient, since the retrieval index is a separate copy of the content and is the actual leak surface.
What to do next
Start with an audit rather than a rewrite. Dump one page of your index and confirm that every chunk carries a permission field, then confirm that your retrieval code always constructs a predicate from a server-derived identity. If either check fails, you have found the leak before a user did. If both pass, add the canary test and the fail-closed check to your test suite, and document how quickly permission changes propagate to the index. Readers who want to compare notes on their own setup — engine, identity source, and the failure they hit — are welcome to share the specifics in the community.
FAQ
Can I just instruct the model not to reveal restricted content?
No. AWS's security guidance treats LLMs as untrusted entities and advises assuming that anything passed into a prompt can be returned to the principal. Restricted chunks must be excluded at retrieval, before they reach the model.
Do I need a specific vector database to do this?
No. The requirement is that your index supports filterable structured fields and that your retriever applies a predicate at query time. Managed features such as Azure AI Search's query-time ACL and RBAC enforcement automate part of this, but the pattern is engine-agnostic.
What happens when a user's group membership changes?
The index keeps serving the old permission state until the metadata is re-synced. Decide whether permission changes trigger re-indexing or are checked against a revocation list at query time, and document the propagation delay.
Does permission-aware retrieval work with local models?
Yes. The filter runs in the retrieval layer, so it is independent of whether generation happens in the cloud or on a local runtime. Self-hosted stacks simply require you to supply the identity mapping and predicate yourself.