Authentication and authorization
NoNoDB uses a small JSON authorization registry managed by nonodb-cli, the
HTTP API, or the GUI, and watched by the daemon. It is deliberately outside
LMDB:
- it survives database restores and cannot be rolled back with an old backup;
- it remains available when the database is unavailable;
- it is not copied into database backups or snapshots;
- it contains only token hashes and certificate fingerprints, never plaintext tokens.
Trust model
Section titled “Trust model”| Source | Identity | Required configuration |
|---|---|---|
| Unix socket | local principal with *:* |
Socket permissions and uid/gid allow-lists |
| TCP | Bearer token or registered client certificate | NONODB_AUTH_FILE is mandatory |
| TCP + mTLS | Registered certificate, optionally combined with a token | NONODB_AUTH_FILE, client CA, TLS cert/key |
TCP never starts without NONODB_AUTH_FILE. There is no global static token
fallback.
The Unix socket is treated as a trusted local administrative channel. Protect
it with filesystem permissions (0660, group nonodb) and, if needed,
NONODB_ALLOWED_UIDS / NONODB_ALLOWED_GIDS.
Auth file
Section titled “Auth file”Default path: /etc/nonodb/auth.json. Override with NONODB_AUTH_FILE.
Recommended permissions:
/etc/nonodb/auth.json root:nonodb 0640/etc/nonodb/ root:nonodb 0750For a Docker bind mount, add the host file’s group to the container
(docker run --group-add "$(id -g)" ...) or use a Compose secret. A 0640
file owned by the host user is not readable by the container’s unprivileged
user without that group.
Example:
{ "version": 1, "principals": { "app": { "scopes": ["read:orders", "write:orders"] }, "reporting": { "scopes": ["read:*"] }, "admin": { "scopes": ["*:*"] } }, "tokens": [ { "kid": "8f31a2c9d104", "sha256": "…64 hex characters…", "principal": "app", "disabled": false } ], "certificates": [ { "sha256": "…64 hex characters…", "principal": "app", "disabled": false } ]}The daemon validates the entire file. Unknown fields, duplicate token IDs, duplicate fingerprints, unknown principals, invalid scopes, or an unsupported version make the file invalid.
Scopes
Section titled “Scopes”| Scope | Allows |
|---|---|
read:<collection> |
find, find_one, lookup, count, aggregate, SQL SELECT, explain_sql, explain, search, fuzzy, vector search, history, get_version, get_collection_ttl, get_collection_history, get_collection_events, get_collection_metrics, list_subscriptions, list indexes |
write:<collection> |
insert, insert_many, update, find_and_modify, delete, SQL INSERT/UPDATE |
admin:<collection> |
create/drop collection, create/drop secondary/text/fuzzy/vector index, set collection TTL, set collection history, set collection events, create/renew/delete subscription |
admin:db |
Instance-wide administration: list_databases, create_database, drop_database, map operations, sync, metrics, and auth management; collection actions still use collection scopes |
metrics:read |
Read /metrics and /metrics/prometheus without granting database administration |
read:* / write:* / admin:* |
The action on every collection in every database |
read:<database>/<collection> |
Same read actions, limited to one database |
write:<database>/<collection> |
Same write actions, limited to one database |
admin:<database>/<collection> |
Collection administration, limited to one database |
read:<database>/* |
Read every collection in one database |
write:<database>/* / admin:<database>/* |
Write or administer every collection in one database |
*:* |
Everything |
Rules:
- Authorization is deny-by-default.
writedoes not implyread; grant both when the workload needs both.admin:<collection>does not implyreadorwrite.write_batchis checked per operation; one forbidden collection rejects the whole request before any write happens.- Unqualified collection scopes such as
read:ordersapply to that collection name in every database. Useread:app1/ordersto restrict one database. list_collectionsreturns only collections visible through any collection scope. A principal withread:ordersdoes not learn thatcustomersexists.- Database management (
create_database,drop_database,map_info,resize_map,/metrics) still requires globaladmin:dbor*:*. /healthzand/readyzare public./metricsand/metrics/prometheusrequiremetrics:read,admin:db, or*:*.- If both a client certificate and a bearer token are used, they must resolve to the same principal.
Tokens
Section titled “Tokens”Create a token:
nonodb-cli auth token create appOutput is a single line:
nodb_8f31a2c9d104_Xq7...The file stores only kid and sha256(secret). The plaintext token is shown
once and cannot be recovered. Use it as:
Authorization: Bearer nodb_8f31a2c9d104_Xq7...Disable a token without deleting its audit history:
nonodb-cli auth token disable 8f31a2c9d104nonodb-cli auth token enable 8f31a2c9d104Certificates and mTLS
Section titled “Certificates and mTLS”Register the SHA-256 fingerprint of the DER-encoded leaf certificate:
FP=$(openssl x509 -in client.crt -outform DER | sha256sum | awk '{print $1}')nonodb-cli auth cert add "$FP" appThe certificate is accepted only when:
- its chain validates against
NONODB_TLS_CLIENT_CA; - its fingerprint is present and enabled in
NONODB_AUTH_FILE; - the referenced principal exists.
Certificate authentication is re-checked on every request, so disabling or removing an entry also blocks existing keep-alive connections. New handshakes are rejected immediately.
Revoke:
nonodb-cli auth cert disable "$FP"There is no CRL or OCSP integration. Revocation is handled by this registry and short-lived client certificates.
MongoDB wire authentication
Section titled “MongoDB wire authentication”The MongoDB-compatible wire listener uses the same SCRAM credential for every connection:
NONODB_MONGO_USERNAME/NONODB_MONGO_PASSWORDconfigure the SCRAM account.NONODB_MONGO_PRINCIPALselects the auth-file principal used for wire authorization. It defaults to the Mongo username.NONODB_MONGO_AUTH_SOURCEdefaults toadminand must match the driver’sauthSource.- If
NONODB_AUTH_FILEis configured, the principal must exist or SCRAM fails. If it is not configured, the listener keeps the legacy full-admin behavior.
Wire commands enforce the mapped principal’s scopes:
find,count,distinct,listIndexes, andaggregaterequire read access;$out/$mergealso require write access to the target collection.insert,update,delete, andfindAndModifyrequire write access.create/dropcollection and index DDL require collection administration.dropDatabaserequiresadmin:db.listCollectionsandlistDatabasesare filtered to visible resources.
This is a single-account mapping, not a MongoDB user database. There are no per-database SCRAM users, MongoDB roles, or X.509 user names yet.
Managing principals
Section titled “Managing principals”nonodb-cli auth initnonodb-cli auth principal add app read:orders,write:ordersnonodb-cli auth principal scopes app read:orders,write:orders,read:customersnonodb-cli auth principal listnonodb-cli auth token create appnonodb-cli auth token listnonodb-cli auth cert add "$FP" appnonodb-cli auth cert listnonodb-cli auth checkauth init creates an admin principal with *:*. It does not create a token;
run auth token create admin next. Use --force to replace an existing file.
The CLI writes the file atomically under an exclusive lock:
- validate the complete new document;
- write a temporary file in the same directory;
fsyncthe file;- rename over the old file;
fsyncthe directory.
HTTP API and GUI
Section titled “HTTP API and GUI”The daemon exposes the same registry operations over HTTP:
GET /v1/authPOST /v1/auth/principalsPUT /v1/auth/principals/{name}DELETE /v1/auth/principals/{name}POST /v1/auth/tokensPATCH /v1/auth/tokens/{kid}POST /v1/auth/certificatesPATCH /v1/auth/certificates/{sha256}All routes require an enabled admin:db principal. The GUI exposes them in the
Authorization tab. Mutations use the same cross-process lock as the CLI,
then reload the registry immediately. The API does not expose token hashes, and
a newly created plaintext token is returned only once.
Safety rules enforced by the HTTP API:
- invalid scopes and duplicate token IDs are rejected;
- a principal referenced by a token or certificate cannot be deleted;
- a change that would leave no enabled administrator token or certificate is
rejected with HTTP
409; - audit logging records the operation and principal, never the token body.
The CLI remains the recovery path if the last administrator is lost or the registry file must be repaired while the daemon is stopped.
Reload and failure behavior
Section titled “Reload and failure behavior”- The daemon loads the file at startup. An invalid file is a startup error.
- When
NONODB_AUTH_FILEis configured, a watcher checks the file every second. - A changed, valid file is swapped in atomically.
- A changed, invalid file is rejected; the daemon keeps the last known good configuration and logs an error. Fix the file and save it again.
- There is no SIGHUP requirement and no restart for token or certificate changes.
Failed-login lockout
Section titled “Failed-login lockout”The daemon can block a TCP peer by IP after repeated failed authentication. Unix socket requests are local administration and are never blocked.
| Variable | Default | Meaning |
|---|---|---|
NONODB_AUTH_MAX_FAILURES |
10 |
Failed attempts in the window before a block; 0 disables lockout |
NONODB_AUTH_FAILURE_WINDOW |
60 |
Sliding window in seconds for counting failures |
NONODB_AUTH_BLOCK_SECS |
300 |
Block duration in seconds; 0 disables lockout |
Behavior:
- Only failed authentication counts: bad/missing bearer token, unregistered or disabled client certificate, or a certificate/token principal mismatch.
- Successful requests do not clear failures. The counter ages out only after
NONODB_AUTH_FAILURE_WINDOW, so successful traffic cannot mask a brute-force attempt. - When the threshold is reached, the client receives HTTP
429with error coderate_limitedand the block starts. - During a block, all HTTP requests from that IP receive
429, including/metrics. mTLS handshakes from a blocked IP are dropped before TLS negotiation. - Blocks are in-memory and process-local. Restarting the daemon clears them.
- The peer address is taken from the TCP socket.
X-Forwarded-Forand similar headers are ignored, so a reverse proxy requires a separate rate-limit layer or a trusted-proxy design. - A block applies to the whole IP. Multiple applications behind one NAT address share the counter and the block.
Lockout settings are read at daemon startup; restart the daemon after changing them. The auth file itself reloads without a restart.
Typical configuration:
export NONODB_AUTH_MAX_FAILURES=5export NONODB_AUTH_FAILURE_WINDOW=300export NONODB_AUTH_BLOCK_SECS=900Tune this above normal user typo rates. For machine-to-machine deployments, a small threshold (3–5) and a short window are usually appropriate. For shared office NAT, use a higher threshold or disable IP lockout and rely on token rotation plus an upstream WAF.
Metrics:
| Metric | Meaning |
|---|---|
auth_failures_total |
Failed authentication attempts |
auth_blocks_total |
Number of lockouts started |
auth_blocked_requests_total |
Requests rejected because the IP was already blocked |
auth_blocked_clients |
Currently blocked IPs |
Audit log
Section titled “Audit log”Enable the append-only JSONL audit log:
export NONODB_AUDIT_LOG=/var/log/nonodb/audit.jsonlRecommended permissions: nonodb:nonodb 0640.
Behavior:
- writes and administrative operations are always logged;
- denied requests are always logged;
- failed logins, lockouts, and blocked requests are always logged;
- reads are optional with
NONODB_AUDIT_READS=1; NONODB_AUDIT_FSYNC=1fsyncs after every line (slower, stronger durability).
Normal record:
{"ts_ms":1794389203533,"principal":"app","source":"tcp","peer":"127.0.0.1:54684","op":"insert","collections":["orders"],"result":"ok","error":null,"duration_ms":1.9}Failed-login record:
{"ts_ms":1794389203533,"principal":"anonymous","source":"tcp","peer":"127.0.0.1:54684","op":"find","collections":["orders"],"result":"error","error":"rate_limited","duration_ms":0.3,"auth_failures":5,"blocked_for_secs":900}auth_failures is the number of attempts in the current window when the record
was written. blocked_for_secs is present when this attempt started a block or
was rejected while blocked. Counting audit records with these fields gives the
number of unauthorized login attempts and lockout events.
mTLS certificate rejection before HTTP is audited as
"op":"tls_handshake" with the same fields.
The audit log never contains bearer tokens, vault keys, certificate private keys, or document bodies. It is outside LMDB, so database restores do not rewrite audit history.
Backups
Section titled “Backups”auth.json and the audit log are not part of nonodb-cli backup. Back them
up separately with filesystem tools and protect them as credentials. The full
backup procedure is in Backup and restore.
install -m 0640 -o root -g nonodb auth.json /var/backups/nonodb/auth.jsonRestoring an old database does not restore old authorization state. This is intentional: a stale backup must not resurrect a revoked token or certificate.