Skip to content

Authentication and authorization

namidb-server requires authentication by default: it refuses to start unless at least one auth source is configured, or you pass --no-auth explicitly. Every source resolves a bearer token to a principal with a role and an optional namespace scope, the same way for HTTP and Bolt.

SourceFlagsBuild feature
One static token--auth-token / NAMIDB_AUTH_TOKENdefault
Tokens file--auth-tokens-file / NAMIDB_AUTH_TOKENS_FILEdefault
OIDC / JWT--jwt-jwks-url and the other --jwt-* flagsjwt
External policy (PDP)--pdp-url / NAMIDB_PDP_URLpdp
None (development only)--no-auth / NAMIDB_NO_AUTH=1default

The official image and release binary include static tokens and the tokens file. JWT and the policy hook need a server built from source with --features jwt,pdp.

Roles

RoleMay
read-writeRun any Cypher, DDL and admin endpoint
read-onlyRun read queries only. Writes, DDL and admin endpoints return 403.

Public routes (/v0/livez, /v0/health, /v0/version, /v0/metrics) need no token. Protect /v0/metrics at the network level if its contents are sensitive for you.

A single token

Terminal window
export NAMIDB_AUTH_TOKEN="$(openssl rand -hex 32)"
namidb-server --store "file:///var/lib/namidb?ns=prod"

The token is read-write. Prefer the environment variable or a tokens file over --auth-token on the command line, which other users of the host can see in the process list.

Tokens file

A JSON file of named tokens, each with a role and an optional namespace scope:

{
"tokens": [
{ "name": "ingest", "token": "…", "role": "read-write" },
{ "name": "dashboard", "token": "…", "role": "read-only" },
{ "name": "acme-app", "token": "…", "role": "read-write", "namespaces": ["acme"] }
]
}
Terminal window
chmod 600 /etc/namidb/tokens.json
namidb-server --store "file:///var/lib/namidb?ns=prod" --auth-tokens-file /etc/namidb/tokens.json
FieldDefaultMeaning
tokenrequiredThe secret. Empty secrets are rejected.
nametoken-<i>Label used in logs and policy input.
roleread-writeread-write or read-only.
namespacesunscopedList of namespaces the token may reach in multi-tenant mode. Omit for all namespaces; [] denies all.
  • The file takes precedence over --auth-token.
  • A file with no tokens is rejected at startup, so a mistake can never leave the server open.
  • Hot reload. The server re-reads the file every --auth-tokens-reload-interval (default 10s; 0s disables) and swaps the token set atomically. Write the file atomically (write a temporary file, then rename it). A malformed or empty file is ignored and the last good set keeps serving.
  • HTTP and multi-tenant Bolt see a reload on the next request or statement. A single-tenant Bolt session keeps the principal it logged in with, so a revoked token stays valid on already-open connections until they close.

Generate a strong secret per client:

Terminal window
openssl rand -hex 32

OIDC / JWT

With the jwt feature, the server validates bearer JWTs from your identity provider against its JWKS. NamiDB only verifies tokens; it never issues them.

Terminal window
namidb-server \
--store "file:///var/lib/namidb?ns=prod" \
--jwt-jwks-url "https://issuer.example.com/.well-known/jwks.json" \
--jwt-issuer "https://issuer.example.com/" \
--jwt-audience "namidb" \
--jwt-groups-claim groups \
--jwt-write-group namidb-writers \
--jwt-read-group namidb-readers
FlagDefaultMeaning
--jwt-jwks-url—Enables JWT validation; signing keys are fetched from here.
--jwt-issuernot checkedRequired iss.
--jwt-audiencenot checkedRequired aud.
--jwt-groups-claimgroupsClaim holding the user’s groups.
--jwt-write-group—Group that grants read-write.
--jwt-read-group—Group that grants read-only. The write group wins if both match.
--jwt-namespaces-claimunscopedClaim listing the namespaces the token may reach (array of strings or one string).

Validation is fail-closed:

  • Only asymmetric algorithms are accepted (RS256, RS384, RS512, ES256, ES384); HS* and none are refused.
  • exp is required (30 s leeway); iss and aud are enforced when configured.
  • A token that fails validation gets 401. An unreachable JWKS at startup aborts the start.
  • The JWKS is refreshed periodically, so key rotation needs no restart.

Static tokens and JWTs can be configured together.

A matching token payload for the flags above plus --jwt-namespaces-claim tenants:

{
"iss": "https://issuer.example.com/",
"aud": "namidb",
"sub": "alice@example.com",
"exp": 1793600000,
"groups": ["namidb-writers"],
"tenants": ["acme"]
}

External policy (PDP)

With the pdp feature, --pdp-url sends every query and DDL statement to an OPA-style policy endpoint before it runs. Use it for rules richer than the read / write split, such as “analysts may read but never touch the Salary label”.

Terminal window
namidb-server --store … --auth-tokens-file … \
--pdp-url "http://opa:8181/v1/data/namidb/allow"

The request body follows the OPA convention:

{
"input": {
"subject": "alice", "role": "read-write", "groups": ["eng"],
"action": "write", "operators": ["Create", "NodeScan"],
"namespace": "acme"
}
}

action is read, write, or a schema operation for DDL; operators lists the plan operators. The request is allowed only for one of these responses:

Endpoint styleAllow response
OPA /v1/data/<path>, object rule{"result": {"allow": true}}
OPA /v1/data/<path>, boolean rule{"result": true}
OPA /v0/data/<path>true
Custom endpoint{"allow": true}

Anything else (a network error, a non-2xx status, a timeout after 5 s, a malformed body, a missing or false decision) denies the request. The policy can deny reads as well as writes.

--no-auth

Terminal window
namidb-server --store memory://dev --no-auth

Every request becomes anonymous read-write and the server logs a loud warning. Use it only on a loopback address for local development. --no-auth accepts true/false/1/0/yes/no/on/off; any other value is an error, so a typo can never disable auth.

Network hygiene

  • Serve TLS directly (TLS) or behind a terminating proxy; bearer tokens on plain HTTP can be sniffed.
  • Bind to 127.0.0.1 or a private interface unless clients must reach the server from elsewhere.
  • Parameterise sensitive values: statement text (but never parameters) appears in the slow-query log and the in-flight query list.
  • Restrict --backup-target-uri to a dedicated backup location; it is the boundary for where admin backups may write. See Backup and restore.