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.
| Source | Flags | Build feature |
|---|---|---|
| One static token | --auth-token / NAMIDB_AUTH_TOKEN | default |
| Tokens file | --auth-tokens-file / NAMIDB_AUTH_TOKENS_FILE | default |
| OIDC / JWT | --jwt-jwks-url and the other --jwt-* flags | jwt |
| External policy (PDP) | --pdp-url / NAMIDB_PDP_URL | pdp |
| None (development only) | --no-auth / NAMIDB_NO_AUTH=1 | default |
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
| Role | May |
|---|---|
read-write | Run any Cypher, DDL and admin endpoint |
read-only | Run 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
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"] } ]}chmod 600 /etc/namidb/tokens.jsonnamidb-server --store "file:///var/lib/namidb?ns=prod" --auth-tokens-file /etc/namidb/tokens.json| Field | Default | Meaning |
|---|---|---|
token | required | The secret. Empty secrets are rejected. |
name | token-<i> | Label used in logs and policy input. |
role | read-write | read-write or read-only. |
namespaces | unscoped | List 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(default10s;0sdisables) 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:
openssl rand -hex 32OIDC / 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.
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| Flag | Default | Meaning |
|---|---|---|
--jwt-jwks-url | — | Enables JWT validation; signing keys are fetched from here. |
--jwt-issuer | not checked | Required iss. |
--jwt-audience | not checked | Required aud. |
--jwt-groups-claim | groups | Claim 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-claim | unscoped | Claim 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*andnoneare refused. expis required (30 s leeway);issandaudare 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”.
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 style | Allow 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
namidb-server --store memory://dev --no-authEvery 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.1or 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-urito a dedicated backup location; it is the boundary for where admin backups may write. See Backup and restore.