Autenticación y autorización
namidb-server requiere autenticación por defecto: se niega a arrancar
salvo que haya al menos una fuente de autenticación configurada, o que
pases --no-auth explícitamente. Cada fuente resuelve un bearer token a
una identidad (principal) con un rol y un alcance opcional por namespace,
de la misma forma para HTTP y para Bolt.
| Fuente | Flags | Feature de compilación |
|---|---|---|
| Un token estático | --auth-token / NAMIDB_AUTH_TOKEN | por defecto |
| Archivo de tokens | --auth-tokens-file / NAMIDB_AUTH_TOKENS_FILE | por defecto |
| OIDC / JWT | --jwt-jwks-url y los demás flags --jwt-* | jwt |
| Política externa (PDP) | --pdp-url / NAMIDB_PDP_URL | pdp |
| Ninguna (solo desarrollo) | --no-auth / NAMIDB_NO_AUTH=1 | por defecto |
La imagen oficial y el binario del release incluyen tokens estáticos y el
archivo de tokens. JWT y el hook de políticas requieren un servidor
compilado desde el código fuente
con --features jwt,pdp.
Roles
| Rol | Puede |
|---|---|
read-write | Ejecutar cualquier Cypher, DDL y endpoint de administración |
read-only | Ejecutar solo consultas de lectura. Las escrituras, el DDL y los endpoints de administración retornan 403. |
Las rutas públicas (/v0/livez, /v0/health, /v0/version,
/v0/metrics) no necesitan token. Protege /v0/metrics a nivel de red si
su contenido es sensible para ti.
Un solo token
export NAMIDB_AUTH_TOKEN="$(openssl rand -hex 32)"namidb-server --store "file:///var/lib/namidb?ns=prod"El token es de lectura y escritura. Prefiere la variable de entorno o un
archivo de tokens antes que --auth-token en la línea de comandos, que
otros usuarios del host pueden ver en la lista de procesos.
Archivo de tokens
Un archivo JSON de tokens con nombre, cada uno con un rol y un alcance opcional por namespace:
{ "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| Campo | Por defecto | Significado |
|---|---|---|
token | obligatorio | El secreto. Los secretos vacíos se rechazan. |
name | token-<i> | Etiqueta que se usa en los logs y en la entrada de políticas. |
role | read-write | read-write o read-only. |
namespaces | sin alcance | Lista de namespaces a los que puede llegar el token en modo multi-tenant. Omítela para todos los namespaces; [] los deniega todos. |
- El archivo tiene prioridad sobre
--auth-token. - Un archivo sin tokens se rechaza al arrancar, así que un error nunca puede dejar el servidor abierto.
- Recarga en caliente. El servidor vuelve a leer el archivo cada
--auth-tokens-reload-interval(por defecto10s;0sdesactiva) y reemplaza el conjunto de tokens de forma atómica. Escribe el archivo de forma atómica (escribe un archivo temporal y luego renómbralo). Un archivo mal formado o vacío se ignora y sigue sirviendo el último conjunto válido. - HTTP y Bolt multi-tenant ven una recarga en la siguiente petición o sentencia. Una sesión Bolt single-tenant conserva la identidad con la que inició sesión, así que un token revocado sigue siendo válido en las conexiones ya abiertas hasta que se cierren.
Genera un secreto robusto por cliente:
openssl rand -hex 32OIDC / JWT
Con la feature jwt, el servidor valida los bearer JWT de tu proveedor de
identidad contra su JWKS. NamiDB solo verifica tokens; nunca los emite.
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 | Por defecto | Significado |
|---|---|---|
--jwt-jwks-url | — | Habilita la validación JWT; las claves de firma se obtienen de aquí. |
--jwt-issuer | no se verifica | iss requerido. |
--jwt-audience | no se verifica | aud requerido. |
--jwt-groups-claim | groups | Claim que contiene los grupos del usuario. |
--jwt-write-group | — | Grupo que otorga read-write. |
--jwt-read-group | — | Grupo que otorga read-only. Si ambos coinciden, gana el grupo de escritura. |
--jwt-namespaces-claim | sin alcance | Claim con la lista de namespaces a los que puede llegar el token (array de strings o un string). |
La validación falla cerrada:
- Solo se aceptan algoritmos asimétricos (
RS256,RS384,RS512,ES256,ES384);HS*ynonese rechazan. expes obligatorio (con 30 s de tolerancia);issyaudse aplican cuando están configurados.- Un token que no pasa la validación recibe 401. Un JWKS inalcanzable al arrancar aborta el arranque.
- El JWKS se refresca periódicamente, así que la rotación de claves no requiere reiniciar.
Los tokens estáticos y los JWT se pueden configurar juntos.
Un payload de token que coincide con los flags anteriores más
--jwt-namespaces-claim tenants:
{ "iss": "https://issuer.example.com/", "aud": "namidb", "sub": "alice@example.com", "exp": 1793600000, "groups": ["namidb-writers"], "tenants": ["acme"]}Política externa (PDP)
Con la feature pdp, --pdp-url envía cada consulta y cada sentencia DDL
a un endpoint de políticas al estilo de OPA antes de ejecutarla. Úsalo para
reglas más ricas que la división lectura / escritura, como “los analistas
pueden leer pero nunca tocar el label Salary”.
namidb-server --store … --auth-tokens-file … \ --pdp-url "http://opa:8181/v1/data/namidb/allow"El cuerpo de la petición sigue la convención de OPA:
{ "input": { "subject": "alice", "role": "read-write", "groups": ["eng"], "action": "write", "operators": ["Create", "NodeScan"], "namespace": "acme" }}action es read, write o una operación de esquema para el DDL;
operators lista los operadores del plan. La petición solo se permite con
una de estas respuestas:
| Estilo de endpoint | Respuesta que permite |
|---|---|
OPA /v1/data/<path>, regla de objeto | {"result": {"allow": true}} |
OPA /v1/data/<path>, regla booleana | {"result": true} |
OPA /v0/data/<path> | true |
| Endpoint propio | {"allow": true} |
Cualquier otra cosa (un error de red, un estado distinto de 2xx, un timeout después de 5 s, un cuerpo mal formado, una decisión ausente o falsa) deniega la petición. La política puede denegar tanto lecturas como escrituras.
--no-auth
namidb-server --store memory://dev --no-authCada petición pasa a ser anónima de lectura y escritura y el servidor
registra una advertencia visible. Úsalo solo en una dirección loopback para
desarrollo local. --no-auth acepta true/false/1/0/yes/no/on/off;
cualquier otro valor es un error, así que un error de tipeo nunca puede
desactivar la autenticación.
Higiene de red
- Sirve TLS directamente (TLS) o detrás de un proxy que termine TLS; los bearer tokens sobre HTTP plano pueden interceptarse.
- Vincula el servidor a
127.0.0.1o a una interfaz privada salvo que los clientes deban llegar a él desde otro lugar. - Parametriza los valores sensibles: el texto de las sentencias (pero nunca los parámetros) aparece en el log de consultas lentas y en la lista de consultas en curso.
- Restringe
--backup-target-uria una ubicación de backups dedicada; es el límite de dónde pueden escribir los backups administrativos. Consulta Backup y restore.