Rls Design Checklist

---
name: rls-design-checklist
description: "Gate-by-gate checklist for designing Tableau row-level security (RLS): mechanism selection (user filter vs entitlement table vs data-policy VDM), implementation verification, performance impact assessment, and the mandatory security-reviewer escalation criteria. Owned by tableau-admin."
---

# RLS Design Checklist

## When to invoke

- Designing RLS for a new Tableau workbook or data source.
- Auditing an existing RLS implementation before a security review.
- A user reports seeing data they should not, or not seeing data they should.
- Migrating RLS from user filters to a data-policy / entitlement-table approach.

## Critical preamble

**RLS is a security control, not a convenience filter.** Every RLS design must be reviewed by `ravenclaude-core/security-reviewer` before production publish. This checklist prepares the design for that review — it does not substitute for it.

## Gate 1 — Choose the RLS mechanism

| Mechanism | How it works | Use when |
|---|---|---|
| **User filter (calculated field)** | `USERNAME()` or `USERDOMAIN()` in a calculated filter; user-to-value mapping in the workbook | Small, stable user-to-dimension mapping; Tableau Server/Cloud with named users |
| **Entitlement table (data-source join)** | Join/blend a permission table that maps `[Username]` → `[Allowed Dimension Value]`; filter on match | Dynamic, database-managed entitlements; many users; self-service permission updates |
| **Virtual Connection / Data Policy (Tableau Cloud)** | Centralised RLS defined once in a Virtual Connection; enforced at the data layer for all downstream workbooks | Multi-workbook or multi-user organisation; Tableau Cloud; need central governance |
| **Initial SQL injection** | Session-level variables injected at connect time; filter applied in SQL | Live connections to databases that support session variables (Snowflake, Redshift, BigQuery) |

**Decision rule:** prefer the entitlement-table or data-policy approach for any deployment with > 20 users or > 1 data source — user filters in workbooks are fragile, duplicated, and hard to audit.

## Gate 2 — Implementation checklist (entitlement table approach)

- [ ] The entitlement table is owned and maintained by IT/data-governance, not embedded in the workbook.
- [ ] The join between the data table and the entitlement table uses the same grain as the RLS dimension (e.g., Region, Business Unit, Customer ID).
- [ ] `USERNAME()` (or `USERDOMAIN()+USERNAME()`) is used as the filter key — **not** a parameter (parameters are not security controls; users can override them).
- [ ] The filter is applied as a **data source filter**, not a view-level filter (data source filters apply to every sheet in the workbook; view-level filters apply only to one sheet).
- [ ] The filter has been tested with at least three user accounts representing different entitlement profiles, including a user with no entitlement (should see zero rows, not an error).
- [ ] Null handling: if `USERNAME()` returns null (unauthenticated embed), the filter defaults to zero rows visible — not all rows.

## Gate 3 — Performance impact assessment

RLS implemented via a join to an entitlement table adds a per-query filter. Measure:

1. **Before RLS**: record average query time on the target workbook (Performance Recording).
2. **After RLS**: record the same query with RLS active for a mid-cardinality user (50–200 allowed values).
3. If query time increases > 2×: add an index on the join key in the entitlement table, or materialise the entitlement join in the extract using Tableau Prep.

High-cardinality RLS (e.g., per-customer data in a 10 M row table, 100 K customers) may require partitioned extracts or Virtual Connections — a single filtered extract for all users will not scale.

## Gate 4 — Security escalation criteria

Escalate to `ravenclaude-core/security-reviewer` whenever ANY of the following are true:

- [ ] The RLS-protected data is classified as PII, PHI, financial, or regulated.
- [ ] The entitlement mapping is user-managed (not IT-managed) — users could expand their own access.
- [ ] The workbook is embedded in an application where the authentication layer is not Tableau's own (Connected Apps / JWT) — the embed auth must enforce the RLS identity.
- [ ] The RLS uses a parameter instead of `USERNAME()` — this is not secure; any user can change a parameter.
- [ ] The same data source is used for both RLS-restricted and unrestricted workbooks — verify that the unrestricted workbook does not expose restricted rows.

## Gate 5 — Ongoing governance

- [ ] Document the RLS design in the workbook description: which field(s) are filtered, which entitlement table, who owns it.
- [ ] Add an entitlement-table health check: a scheduled query that alerts if the entitlement table is empty or returns null for active users.
- [ ] Include RLS testing in the content-promotion runbook (dev→test→prod): a named test user per environment whose entitlement is fixed and tested on every promotion.
- [ ] Review entitlement table accuracy quarterly — departed employees who retain entitlements are the most common RLS audit finding.

## Pitfalls

- A user filter built into the workbook as a calculated field with a hardcoded mapping — breaks every time a user is added/removed; must be edited in every workbook.
- RLS applied only on a "Total" sheet but not on the underlying detail sheet — users navigate directly to the detail via a URL and see unfiltered data.
- Testing RLS only with the workbook owner's account — the owner bypasses RLS (Tableau Server). Always test with a named test user with no admin rights.
- Using `ISMEMBEROF()` (group membership) as the RLS control — group membership changes are often delayed by AD sync; test the lag before relying on it.