Fine‑Grained, Context‑Aware Authorization with SpiceDB’s Dynamic ACLs and Policy Templates

Why you need context‑aware rules

Traditional role‑based access control (RBAC) hard‑codes permissions in a flat table. When the business logic depends on object metadata—like a document’s tags, owner, or classification—RBAC becomes a maintenance nightmare. SpiceDB solves this by evaluating policies at request time, letting rules reference object attributes directly. The result is a single source of truth that adapts automatically as data changes.

Core concepts: dynamic ACLs and policy templates

• Dynamic ACLs: Policies that reference attributes on the target object. Example: “allow read if object has tag ‘public’.” The ACL is re‑evaluated for each request, so updating the tag instantly changes access.
• Policy templates: Parameterized rule patterns that you can instantiate for many objects. Templates reduce duplication and make large policy sets easier to maintain.
• gql (GraphQL‑like query language): SpiceDB’s policy engine uses a small, expressive language to declare rules. It supports recursion (e.g., hierarchical groups) but enforces a depth limit to avoid infinite loops.
• Cache: A built‑in in‑memory cache that stores the results of recent evaluations, drastically reducing latency on repeated checks.

Concrete example: “public” tag grants read access

Assume you have a collection of documents stored in a database. Each document has an attribute tags (array of strings). You want any user to read a document if it carries the public tag.

1. Create a policy template

   # Run on the SpiceDB server (requires admin privileges)
   spicedb create-policy-template \
     --name read-public \
     --resource-type document \
     --condition "document.tags contains 'public'"
   

   Explanation:

   • --name is an identifier for the template.
   • --resource-type specifies the SpiceDB type you’re authorizing.
   • The --condition is a gql expression that evaluates to true when the object’s tags array contains the string public.
2. Instantiate the template for a specific document

   # Assume document ID is abc123
   spicedb create-policy \
     --template read-public \
     --resource-id abc123 \
     --effect allow \
     --action read
   

   This creates a concrete policy that applies the template condition to the document with ID abc123.

3. Evaluate access for a user

   # User alice wants to read abc123
   spicedb authz \
     --user alice \
     --resource document:abc123 \
     --action read
   

   Expected outcome: ALLOW if the document’s tags include public; otherwise DENY. The engine logs the evaluation path, including any policy references and the final decision.

4. Verify the result

   Run the same command after removing the public tag from the document. The response should now be DENY, proving the rule is truly dynamic.

Trade‑offs and limitations

• Recursion depth: Policies that reference other policies (e.g., group membership) can hit the engine’s recursion limit (default 10). Exceeding it aborts evaluation with a clear error. Design policies with bounded depth and test with spicedb authz --debug to catch early.
• Template parameter safety: If you bind variables from untrusted input, you risk unintentionally granting access. Always validate parameters before instantiation, and use the policy viewer to audit active rules.
• Database indexing: SpiceDB stores policy and object data in PostgreSQL. Missing or incorrect indexes on columns used in --condition expressions can lead to slow evaluations. Ensure tags is indexed as a GIN array column.
• Over‑permissive defaults: A catch‑all policy that allows all actions can expose data if not overridden. Use the spicedb policy-viewer to inspect the effective policy set before deploying.

Performance considerations

The cost of an authorization check grows with the number of matching policies. In benchmarks with 10,000 policies, enabling the built‑in cache reduced average latency from ~120 ms to ~15 ms. To benefit:

• Keep the cache enabled (spicedb start --enable-cache).
• Group related policies into templates to avoid duplication.
• Periodically run spicedb policy-viewer --compact to identify and prune unused rules.

Actionable next steps

1. Deploy a local SpiceDB instance (docker run -p 50051:50051 ghcr.io/authzed/spicedb:latest) and import your existing object schema.
2. Start with a single policy template (like the public example) and iterate on more complex conditions.
3. Enable the cache and monitor spicedb metrics for hit rates.
4. Use the policy viewer to audit the effective policy set after each change.
5. Automate policy evaluation tests in your CI pipeline (e.g., spicedb authz --user test --resource ...).

By separating policy logic from data and leveraging dynamic ACLs, SpiceDB lets you write flexible, maintainable authorization rules that adapt automatically as your data evolves. If your application needs fine‑grained, context‑aware access control without the overhead of custom code, SpiceDB’s policy templates and caching mechanisms provide a strong foundation to build on.