Saltearse al contenido

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.

FuenteFlagsFeature de compilación
Un token estático--auth-token / NAMIDB_AUTH_TOKENpor defecto
Archivo de tokens--auth-tokens-file / NAMIDB_AUTH_TOKENS_FILEpor defecto
OIDC / JWT--jwt-jwks-url y los demás flags --jwt-*jwt
Política externa (PDP)--pdp-url / NAMIDB_PDP_URLpdp
Ninguna (solo desarrollo)--no-auth / NAMIDB_NO_AUTH=1por 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

RolPuede
read-writeEjecutar cualquier Cypher, DDL y endpoint de administración
read-onlyEjecutar 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

Ventana de terminal
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"] }
]
}
Ventana de terminal
chmod 600 /etc/namidb/tokens.json
namidb-server --store "file:///var/lib/namidb?ns=prod" --auth-tokens-file /etc/namidb/tokens.json
CampoPor defectoSignificado
tokenobligatorioEl secreto. Los secretos vacíos se rechazan.
nametoken-<i>Etiqueta que se usa en los logs y en la entrada de políticas.
roleread-writeread-write o read-only.
namespacessin alcanceLista 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 defecto 10s; 0s desactiva) 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:

Ventana de terminal
openssl rand -hex 32

OIDC / 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.

Ventana de terminal
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
FlagPor defectoSignificado
--jwt-jwks-url—Habilita la validación JWT; las claves de firma se obtienen de aquí.
--jwt-issuerno se verificaiss requerido.
--jwt-audienceno se verificaaud requerido.
--jwt-groups-claimgroupsClaim 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-claimsin alcanceClaim 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* y none se rechazan.
  • exp es obligatorio (con 30 s de tolerancia); iss y aud se 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”.

Ventana de terminal
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 endpointRespuesta 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

Ventana de terminal
namidb-server --store memory://dev --no-auth

Cada 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.1 o 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-uri a una ubicación de backups dedicada; es el límite de dónde pueden escribir los backups administrativos. Consulta Backup y restore.