Database Auth

Database-Backed Auth

auth:
  environmentEnabled: false
  dbEnabled: true

  dbAuth:
    driver: "sqlite"
    dsn: "./auth.db"
    table: "users"
    tokenColumn: "token"
    roleColumn: "role"
    roles:
      admin: "admin"
      readWrite: "rw"
      readOnly: "ro"
    cache:
      capacity: 10000
      ttlSeconds: 300

When dbEnabled is set to true, Conduit connects to the configured database and uses the specified table to authenticate incoming requests.

Required Table Structure

The authorization table must contain at least two columns:

• tokenColumn — stores the API token
• roleColumn — stores the role associated with the token

Example table (SQLite):

CREATE TABLE users (
  token TEXT PRIMARY KEY,
  role  TEXT NOT NULL
);

Role Mapping

The roles section maps database role values to Conduit’s internal role system. Database values are normalized to lowercase before matching.

roles:
  admin: "admin"
  readWrite: "rw"
  readOnly: "ro"

If a database role does not match any configured mapping, Conduit defaults to ReadOnly.

Permissions

Database-backed auth supports three roles:

• Admin — full access to all actions
• ReadWrite — can read and write, but cannot mutate schema
• ReadOnly — can only perform read operations

Action evaluation:

ActionReadTable      → allowed for all roles
ActionWriteTable     → allowed for Admin and ReadWrite
ActionMutateSchema   → allowed only for Admin

Driver-Specific Query Syntax

Conduit automatically adjusts the SQL placeholder syntax depending on the database driver:

• SQLite / MySQL — ?
• PostgreSQL — $1
• SQL Server — @p1

Example PostgreSQL query generated by Conduit:

SELECT role FROM users WHERE token = $1

Token Caching

Conduit uses a TTL-based LRU cache to reduce database load. Cached entries include:

• Valid role values
• Invalid tokens (stored as a sentinel)

Cache settings:

cache:
  capacity: 10000
  ttlSeconds: 300

Invalid tokens are cached to prevent repeated database lookups for unauthorized clients.

Noop Mode

Database auth enters noop mode if any required configuration is missing:

• table is empty
• tokenColumn is empty
• roleColumn is empty
• roles mapping is empty

In noop mode, the authenticator reports itself as inactive and performs no authorization.

Example

auth:
  dbEnabled: true

  dbAuth:
    driver: "postgres"
    dsn: "postgres://user:pass@localhost:5432/authdb"
    table: "api_tokens"
    tokenColumn: "token"
    roleColumn: "role"
    roles:
      admin: "admin"
      readWrite: "rw"
      readOnly: "ro"
    cache:
      capacity: 5000
      ttlSeconds: 120

A client using the ReadWrite token would authenticate with:

Authorization: Bearer rw-secret