Enforcing patient-level access control on LlamaIndex metadata filters in healthcare RAG systems
A metadata filter narrows what a retriever searches. It does not decide who may see what. To enforce patient-level access, derive the patient scope on the server from verified caller identity and entitlements, inject it where the model cannot alter it, deny when the scope is missing or unusable, verify returned nodes before they reach the model, and record each decision as evidence.
Evidence to keep for each retrieval
- Authenticated principal, including service or agent identity
- Patient scope applied and where it came from
- Filter exactly as sent to the vector store
- Identifiers of returned nodes and their patient IDs
- Decision (allow, deny, block) and the rule that produced it
- Timestamp and the tool call or request it belongs to
Why a metadata filter is not an authorization boundary
In LlamaIndex, a MetadataFilters object is a parameter on a retrieval query. It expresses which stored nodes are eligible for similarity search, for example those tagged with a given patient ID. That is a retrieval mechanism. Whether the caller is allowed to see that patient's data is a separate question, and nothing in the filter answers it.
The filter becomes a weak control because of how it is usually supplied. Several failure modes recur in healthcare designs:
The filter is omitted, and the retriever returns the nearest matches across every patient in the index. The filter is generated from model output, so a prompt that names another patient, or injected text in a retrieved document, can change the scope. The filter is overridden or merged carelessly, so a caller-supplied value replaces the intended one. The filter is malformed or uses an operator a backend handles differently, and depending on the integration it may be rejected, ignored or interpreted differently. Finally, some retrieval paths never use the filter at all, such as keyword search, document lookup tools, or cached results.
Filter semantics can also differ between vector store backends, so the same filter object is not guaranteed to mean the same thing everywhere. Treat each of these as a way to retrieve another patient's PHI, and design so that none of them depends on the model or the prompt behaving correctly.
Derive patient scope from verified identity
The HIPAA Security Rule gives the design its shape. Under 45 CFR 164.312(a)(1), technical policies must allow access to ePHI only to those persons or software programs that have been granted access rights as specified in 164.308(a)(4). Under 164.312(d), procedures must verify that a person or entity seeking access is the one claimed. The reference to software programs matters: the RAG service, the retriever, and any agent or tool are access subjects, not just the clinician at the keyboard.
In practice, this suggests a pattern in which the scope is computed, never accepted. Authenticate the caller at the service boundary. Resolve that identity to an entitlement set, meaning the patients the caller is permitted to access in the current context, from an authoritative store outside the model's reach. Build the metadata filter from that set in application code. If a user names a patient in the prompt or a request field, treat it only as a selection to be checked for membership in the entitlement set, never as the scope itself.
Combine the server-derived constraint with any other application filters using AND semantics, so nothing can widen it. Expose a retriever wrapper to the rest of the codebase and keep the raw retriever out of reach, so no code path can query without the injected scope. Where the backend supports it, add a second layer such as per-tenant or per-patient partitioning, so a filter defect does not become a data exposure by itself.
Deny by default and verify after retrieval
Because access is limited to granted rights, a scope that is missing, empty or unresolvable should fail closed. If identity cannot be verified, the entitlement lookup fails, or the filter cannot be constructed, return a denial and record it. Do not fall back to an unfiltered query.
Add a post-retrieval check as an independent control. Before any node enters the prompt, compare its patient identifier metadata to the permitted scope. Drop or block nodes that fall outside it, and treat nodes with no identifier as out of scope. A mismatch means the filter did not do its job, so it should raise an alert rather than quietly trim results.
Test each vector store backend you run, because filter behavior is a property of the integration. A useful matrix covers an absent filter, a malformed filter, an unsupported operator, a caller-supplied override, multi-patient scopes, and every filter-less retrieval path, with the observed result recorded for each. Apply the same identity binding to tool calls that fetch documents or records, since they are also software programs acting on ePHI.
One governance note: denying automated or agentic access can raise information blocking questions. Document the basis for each restriction so a denial can be explained as a deliberate access decision.
- Identity unverified: deny and record
- Entitlement set empty or lookup failed: deny and record
- Filter cannot be built or backend rejects it: deny, never fall back to unfiltered retrieval
- Returned node outside scope: block the response and alert
- Node missing patient identifier: treat as out of scope
Where runtime policy enforcement fits
Application code, the vector store and the execution path each enforce different things. Application code derives scope and builds the filter. Vector store controls, where available, limit what a credential or partition can reach. Neither sees the full interaction: what the model asked a tool to do, what came back, and what was about to be returned to the user.
This is where Trussed applies. Trussed enforces policy in the execution path, at runtime, not reviewed after the fact, on individual interactions and tool calls. For retrieval, that means an outcome of allow, redact or block can be applied to what is retrieved or called before it reaches the model or the response. Enforcement generates audit-ready evidence mapped to HIPAA, including 164.312(b) audit controls. Trussed runs in production with healthcare and pharma organizations and can be deployed self-managed in the customer's cloud.
The scope is deliberately narrow. Runtime enforcement complements identity binding and entitlement design. It does not replace them, and it does not make a system compliant on its own.
Patient scope bound to the caller, not the prompt
Verify identity
Authenticate the person or service making the request.
Resolve entitlements
Look up the patients this caller may access, server side.
Inject the filter
Build the retrieval filter in code the model cannot reach.
Verify results
Check every returned node against the permitted scope.
Record the decision
Keep who, what scope, what was returned, and why.
Review your retrieval path for patient-level enforcement
Walk through how scope is derived, enforced and evidenced on retrieval and tool calls in your healthcare RAG system.
Explore Agent and Tool-Call EnforcementHow does your AI governance program compare?
See where your program has gaps in less than 2 minutes.