Auth & Security

Relata DB 3.0
This page describes Relata DB 3.0: local authentication only (registry tokens, TLS, mTLS), one tenant and a minimal local audit log. Single sign-on, tamper-evident audit, managed users and KMS key management are not part of the open edition. See What is new in 3.0 and Governance and audit.

Security sits in the query path. Every read runs through the ABAC engine, and classified or masked columns are redacted before serialisation. Authentication is a configuration decision, not a licensed tier.

Authentication model

Relata DB authenticates locally. Your application authenticates its own users (SSO, OIDC, SAML belong to the application layer) and calls the database with a service token.

Mode (RELATA_AUTH_MODE)When to useCredential
bearer (default)Every deploymentAuthorization: Bearer <registry token>
mtlsService-to-service behind a TLS terminator that validates client certificatesX-Client-Cert-Subject forwarded by the terminator
noneIsolated local development onlynone

RELATA_AUTH_MODE=oidc, oidc-proxy, oidc-verify and saml, the RELATA_OIDC_* and RELATA_SAML_* variables and RELATA_TRUST_UPSTREAM_PROXY were removed. The server refuses to start if any is set. A JWT is never a data-plane credential.

A token-less relata serve refuses to start. The unauthenticated local-dev convenience exists only behind RELATA_AUTH_MODE=none plus RELATA_OPEN_DEV_ALLOWED=true and a loopback bind; it stays closed if the listener is reachable off the machine.

Step 1: set the bootstrap secrets

export RELATA_BEARER_TOKEN=$(openssl rand -hex 32)
export RELATA_ADMIN_TOKEN=$(openssl rand -hex 32)
relata serve

The two values must be distinct. RELATA_BEARER_TOKEN is a loopback-only bootstrap secret and never authenticates the data plane. RELATA_ADMIN_TOKEN gates the admin surface and is not a fallback for data access. The data plane accepts only live registry tokens.

Step 2: mint a registry token

The admin surface (/admin/*) is on a separate listener, RELATA_ADMIN_BIND (default 127.0.0.1:9091, which must resolve to loopback). It is not mounted on the data-plane port: a request to :9090/admin/tokens answers 404.

curl -X POST http://127.0.0.1:9091/admin/tokens \
  -H "Authorization: Bearer $RELATA_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"description\":\"my-app\",\"expires_at\":$(( $(date +%s) + 365*86400 ))}"
# { "token": "rlt_...", "id": "tok_..." }

expires_at is an absolute Unix-epoch-seconds timestamp. Omit it for a token that never expires. Expiry is evaluated on every request.

Check the split:

# 401: the bootstrap secret is not a data-plane credential
curl -s -o /dev/null -w "%{http_code}\n" -H "Authorization: Bearer $RELATA_BEARER_TOKEN" http://localhost:9090/v1/query
# 200: health does not need a data-plane token
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:9090/health

Token lifecycle

# Rotate your own token (no admin token needed)
curl -X POST http://localhost:9090/v1/auth/tokens/self/rotate -H "Authorization: Bearer rlt_..."
 
# List your tokens and view their audit trail
curl http://localhost:9090/v1/auth/tokens/self       -H "Authorization: Bearer rlt_..."
curl http://localhost:9090/v1/auth/tokens/self/audit -H "Authorization: Bearer rlt_..."
 
# Revoke one of your own tokens
curl -X DELETE http://localhost:9090/v1/auth/tokens/self/tok_abc123 -H "Authorization: Bearer rlt_..."
 
# Operator: revoke or rotate any token (admin listener)
curl -X DELETE http://127.0.0.1:9091/admin/tokens/tok_abc123 -H "Authorization: Bearer $RELATA_ADMIN_TOKEN"

Revocation and rotation take effect on the next request, and revoked, rotated-out and expired secrets stay dead after a restart. The admin secret is not accepted on /v1/auth/tokens/self/*. Tokens within 30 days of expiry are logged at WARN on each use.

Reaching the admin listener from another container

The admin listener is loopback-only by design. Mint the token from inside the Relata container (docker exec or kubectl exec), or from a sidecar that shares its network namespace, and hand the resulting token to the other service as a secret. That service can then rotate its own token through POST /v1/auth/tokens/self/rotate on the data-plane port. There is no supported way for a different container to reach the admin bind directly.

Asserting an end-user principal

An application that has authenticated a user passes the user's id so cell-level ACL and masking are evaluated for that user, with no user directory in the database.

  1. Mint a service token that may assert: POST /admin/tokens {"description":"billing-app","can_assert_principal":true}. Only the admin token can set the flag.
  2. The application sends Authorization: Bearer <service token> and X-Relata-Principal: <end-user id> on each request.
  3. The id is validated, never sanitised: 1 to 128 characters of A-Z a-z 0-9 _ . - @, header sent exactly once.
  4. ACL policies are written against the principal app:<id>. An asserted user does not inherit the service token's role, so a user with no grants is denied. Grant users with RELATA_ACL_GRANT_APP (for example alice=Patient:read;bob=Patient:read+write).

An X-Relata-Principal header sent with an ordinary token, the bootstrap token or no token is rejected with 400 principal-assertion-not-permitted. A service token that can assert can act as any end-user id for ACL purposes: store it like a signing key and give it a short expires_at.

Transport

Terminate TLS in-process with RELATA_TLS_CERT and RELATA_TLS_KEY, or at a reverse proxy. A non-loopback bind requires TLS unless you set RELATA_PLAINTEXT_OK=true for a proxy-terminated deployment.

For mutual TLS, terminate mTLS at the proxy, forward the client certificate subject, and set the mode:

RELATA_AUTH_MODE=mtls RELATA_MTLS_CA_CERT_PATH=/etc/relata/tls/ca.crt relata serve

Use HTTPS for any object-store endpoint. Plain HTTP is rejected unless RELATA_ALLOW_HTTP_OBJECT_STORE=true, which must not be used in production.

Brute-force protection and rate limits

After RELATA_AUTH_LOCKOUT_FAILURE_THRESHOLD consecutive failures from one address, further bad credentials from it answer 401 with Retry-After. X-Forwarded-For is honoured only from a peer listed in RELATA_TRUSTED_PROXIES, so a spoofed header does not escape the lockout. Identity headers such as X-Relata-Principal, X-Organization-Id and X-Forwarded-User authenticate nobody on their own.

Per-IP rate limits apply to every request path: RELATA_RATE_LIMIT_RPS (default 10000) and RELATA_RATE_LIMIT_AUTH_FAIL_RPS (default 10 on a non-loopback bind). Exhaustion returns 429 with Retry-After. Keep the auth-failure limit low in production.

Purpose enforcement

PURPOSE is optional in SQL. When declared it is recorded in the audit log and evaluated by the ACL engine.

PURPOSE 'analytics' SELECT name, email FROM Person LIMIT 10;

Lock down to a registered list in production:

RELATA_PURPOSE_MODE=strict RELATA_PURPOSES=analytics,audit,compliance relata serve

An unregistered purpose is refused with 403 on SQL, /v1/memory/*, MCP tools and A2A skills alike.

Policy engine (ABAC)

Relata uses a Cedar-inspired ABAC engine with deny-wins semantics. Policy is read once at startup (RELATA_ACL_GRANT*, RELATA_CEDAR_POLICY_FILE, RELATA_CONDITIONAL_POLICIES_FILE); changing a rule needs a restart. Governed planning applies, in order: access scope, purpose, the ACL policy table (deny-wins) and tenant isolation. EXPLAIN POLICY FOR PURPOSE 'analytics' ON Person; shows which rows are visible, which columns are masked and which deny rules fired; run it after every policy change.

Cell masking and tokenization

export RELATA_CELL_POLICIES='Person.ssn=mask'

A malformed policy prevents startup. A tokenized column is joinable and groupable on its surrogate token, but WHERE and ORDER BY on it return REL_MASKED_COLUMN (400), so a caller cannot confirm guessed plaintext values. The tokenization key is provisioned as <data-dir>/tokenize.key (mode 0600), is carried in backups, and losing it changes every token.

Row-level conditional deny

RELATA_CONDITIONAL_POLICIES_FILE points at a validated, deny-only JSON file. Rules restrict existing grants and never grant access.

{
  "policies": [
    {
      "principal": "http-client",
      "object_type": "Person",
      "action": "read",
      "effect": "deny",
      "condition": { "field": "classification", "op": "eq", "value": "SECRET" }
    }
  ]
}

Operations are eq, ne, gt and lt. Unknown fields, conditional allows, non-read actions, wildcard types and duplicate rules prevent startup. principal must match the role of the request (http-client for HTTP, mcp-client for MCP). Counts, sums, facets, totals, cursors and graph paths are computed over the rows the caller may see, and a hidden row answers exactly like an absent one.

Role separation and node-wide figures

  • POST /v1/gdpr/erase and the legal-hold routes answer 403 role-separation to tokens with the oversight, auditor, schema-admin, platform-admin or media-processor role.
  • GET /v1/system/status returns liveness only to a tenant-scoped token; node-wide counters are for unscoped and oversight tokens.
  • Asynchronous operations (Prefer: respond-async) are bound to the tenant and the principal that started them; any other caller sees 404.

GDPR erasure and audit

ERASE SUBJECT 'person-42' REASON 'gdpr-art17' CERTIFY; shreds the subject's rows, destroys orphaned blobs and returns a signed receipt; the signing key is provisioned as <data-dir>/erasure-signing.key (mode 0600), included in backups, and must be protected like the data directory. See Privacy and GDPR. The open edition keeps a minimal local audit log at GET /v1/audit/log; see Governance and audit.

See also