Seguridad y Autenticación

Seguridad y Autenticación

PgArachne se basa completamente en el sistema de permisos de PostgreSQL. No reinventa las Listas de Control de Acceso (ACLs). La mayoría de los métodos de autenticación ejecutan las consultas bajo el rol de base de datos específico del usuario autenticado usando SET LOCAL ROLE.

1. Inicio de Sesión Interactivo (JWT)

Los usuarios se autentican usando su nombre de usuario y contraseña reales de PostgreSQL a través del método JSON-RPC get_jwt. Si tiene éxito, reciben un JWT de corta duración. Las peticiones posteriores incluyen este token en el encabezado Authorization: Bearer <token>, y PgArachne cambia el rol activo a ese usuario durante la duración de cada petición.

2. Cuentas de Servicio (Tokens de API)

Para sistemas automatizados o scripts, se pueden usar tokens de API de larga duración.

• Los tokens se almacenan en la tabla pgarachne.api_tokens.
• Cada token se asigna a un usuario/rol de base de datos específico.
• Se envía el token a través del encabezado Authorization: Bearer <token>.

Crear tokens API requiere pgarachne_admin. Use pgarachne.add_api_token(...) con un rol que sea miembro de pgarachne_admin.

3. Proveedor de identidad externo (JWT propio)

Si se autentican usuarios fuera de PgArachne (por ejemplo con un servicio de autenticación externo), es posible emitir JWT allí y enviarlos directamente a PgArachne.

• Formato del header: Authorization: Bearer <jwt>.
• Firma: solo HMAC (HS256/HS384/HS512) con el mismo JWT_SECRET configurado en PgArachne.
• Claims obligatorios: db_role (string, no vacío) y db_name (string, debe coincidir con /api/:database).
• Claim recomendado: exp (timestamp Unix) para expiración del token.

Ejemplo mínimo de payload:

{
  "db_role": "demo_user",
  "db_name": "my_database",
  "exp": 1767225600
}

Importante: los algoritmos JWT asimétricos (por ejemplo RS256/ES256) no son aceptados por la implementación actual del servidor.

4. Credenciales directas de base de datos (Basic Auth)

PgArachne admite autenticación HTTP Basic, lo que permite enviar el nombre de usuario y la contraseña de PostgreSQL directamente en cada petición. Al usar este método, PgArachne establece una conexión directa a PostgreSQL con esas credenciales sin necesidad de JWT.

Encabezado HTTP requerido:

Authorization: Basic <base64(usuario:contraseña)>

Ejemplo con curl:

curl -u demo_user:contraseña \
  -X POST http://localhost:8080/db/my_database/jsonrpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"api.hello_world","params":{},"id":1}'

Diferencias clave respecto a los métodos 1–3:

• Sin GRANT necesario: no es preciso ejecutar GRANT usuario TO pgarachne.
• Sin SET LOCAL ROLE: PgArachne se conecta directamente como el usuario indicado, sin cambio de rol.
• Pool de conexiones por usuario: cada usuario dispone de su propio pool con una vida útil de 5 minutos.
• JWT opcional: este método no requiere configurar JWT_SECRET.
• Claves de idempotencia: para que funcionen con credenciales directas, otorgue al usuario EXECUTE ON FUNCTION pgarachne.save_idempotency_key(text).

Comparativa de métodos de autenticación

-- Permitir a 'pgarachne' cambiar a 'demo_user'
GRANT demo_user TO pgarachne;

Ver también

• Configuración
• Códigos de Error