Security Overview

Unified Security is Semaphor's model for controlling data access across the platform. It lets you define security policies on a connection, then assign them to specific actors -- tenants, tenant users, or organization users -- so each person sees only the data they should.

Three policy primitives cover the most common multi-tenant isolation patterns:

You can use these individually or combine them. A tenant might connect to a dedicated database (CLS), operate within a specific schema (SLS), and still have row-level filtering applied (RLS).

How It Works

Unified Security follows a three-step model: define, assign, resolve.

1. Define policies on connections

An admin creates policy definitions on a connection. A policy definition is a reusable template with placeholders for values that vary per actor.

tenant_id = {{ tenant_id }}

postgresql://app:{{ password }}@db.company.com:5432/{{ tenant_db }}

A single policy definition can include CLS, SLS, and RLS rules together, or any subset.

2. Assign policies to actors

An admin creates assignments that bind a policy definition to a specific actor scope and fill in the placeholder values.

For example, assigning the RLS policy definition above to tenant "Acme Corp" with tenant_id = "acme" means every Acme user will have WHERE tenant_id = 'acme' applied to their queries.

3. Resolve at runtime

When a user runs a query, Semaphor resolves their effective security context by collecting all applicable assignments, merging them according to each policy type's rules, and applying the result to the query before execution.

Actor identity + Applicable assignments + securityParams = Effective security context

The resolved CLS configures the connection, SLS pins the schema, and RLS predicates are injected as WHERE clauses -- all before the query reaches the database.

Actor Model

Unified Security supports four assignment scopes that target different levels of your user hierarchy:

Tenant assignment scopes

Persisted RLS does not require an ALL_TENANTS assignment. Each applicable assignment activates its definition for the targeted actor:

• ALL_TENANTS activates the definition for every tenant actor.
• TENANT independently activates it for one tenant.
• TENANT_USER independently activates it for one user in a tenant.

When more than one applicable assignment supplies the same assignment-owned RLS parameter, the most specific supplied value wins:

TENANT_USER → TENANT → ALL_TENANTS

This is value precedence, not SQL narrowing. Semaphor retains every matching rule from every active definition and combines rules for the same secured entity with AND.

Organization users

Org-user assignments are independent -- they do not participate in tenant assignment precedence. If an org user has no applicable assignment, no persisted Unified Security policy definition is applied to that actor. Other connection, token, and authorization controls still apply.

Connection Security Mode

Each connection operates in one of two security modes:

This is a per-connection setting, not project-wide. You can migrate connections one at a time while the rest continue using legacy security.

Migration path

1. Start with all connections in legacy mode.
2. Author Unified Security policy definitions and assignments (this has no runtime effect while in legacy).
3. Preview the resolved security for different actors to verify correctness.
4. Switch the connection to unified mode.
5. If issues arise, switch back to legacy -- policy definitions and assignments are preserved.

When to Use What

Choose your policy type based on how your data is organized:

Most multi-tenant applications need at least one of CLS or SLS for tenant isolation, often combined with RLS for finer-grained access control within the tenant boundary.

Key Concepts

Before diving into configuration, here are the terms you will encounter throughout the security documentation:

• Policy Definition -- A reusable security policy template attached to a connection. Contains CLS, SLS, and/or RLS configuration with placeholder parameters.
• Assignment -- Binds a policy definition to an actor scope (ALL_TENANTS, TENANT, TENANT_USER, or ORG_USER) with concrete parameter values.
• Resolution -- The runtime process that collects applicable assignments for the current actor and merges them into an effective security context.
• Security mode -- The per-connection setting (legacy or unified) that controls which security model is active.

Next Steps