Suplantación de usuario
Actúe en nombre de cualquier usuario para soporte y depuración sin solicitar su contraseña. Limitado a 10 minutos, estrictamente auditado en registros de seguridad.
¿Qué es la suplantación?#
La suplantación de usuario permite a un administrador o ingeniero de soporte generar un token de portador de corta duración que actúa como un usuario específico. Esto permite reproducir errores de los clientes, verificar los permisos de la política RLS o solucionar problemas de datos sin solicitar credenciales.
La suplantación en Aurabase garantiza tres principios de seguridad fundamentales:
- Vida útil corta: los tokens de suplantación son válidos entre 1 y 600 segundos (10 minutos como máximo, por defecto 300 segundos). Nunca incluyen un token de actualización.
- Atribución explícita del actor: el token de acceso emitido lleva el reclamo estándar RFC 8693
actque indica quién inició la sesión. - Auditoría antes de la emisión: la acción se registra en
auth_audit_logcon el actor, el motivo, la duración y el usuario objetivo antes de que se genere el token. Si falla la inserción del registro, no se emite ningún token.
Estructura de reclamo de la ley RFC 8693#
Un token de suplantación se firma con la clave ES256 activa del proyecto y se ajusta al formato de token de acceso de usuario estándar, con un objeto act (actor) adicional:
{
"sub": "b2f4c3a1-7788-4e89-a5c2-98e3b1234567",
"project_id": "ecd48fb4-4fe6-48d0-a8cd-f0641ceb8b1c",
"role": "authenticated",
"email": "user@example.com",
"act": {
"sub": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
},
"exp": 1730000300,
"iat": 1730000000,
"iss": "https://auth-lab-n7qn5stb.localhost:8080/v1/auth"
}
sub: La identidad del usuario que se está suplantando. Postgres RLS (auth.uid()) se evalúa a este valor.act.sub: la identidad del operador que generó el token (por ejemplo, ID de usuario de la consola oservice_role).
Punto final de administrador#
La suplantación requiere autorización de administrador a través de una clave service_role o un operador con el rol admin.
curl -X POST "$AURABASE_URL/v1/auth/admin/users/$TARGET_USER_ID/impersonate" \
-H "apikey: $AURABASE_SERVICE_ROLE_KEY" \
-H "Authorization: Bearer $AURABASE_SERVICE_ROLE_KEY" \
-H "Content-Type: application/json" \
-d '{
"reason": "Investigating ticket #4812",
"ttl_seconds": 300,
"allow_privileged": false
}'
Cuerpo de la solicitud
| campo | Tipo | Requerido | Descripción |
|---|---|---|---|
reason | cuerda | Opcional | Justificación registrada en registros de seguridad. Requerido para cuentas de destino privilegiadas (admin/owner). |
ttl_seconds | numero | Opcional | Duración del token en segundos (de 1 a 600, por defecto 300). |
allow_privileged | booleano | Opcional | Debe establecerse en true si el usuario de destino tiene una función admin o owner. |
Respuesta (200 OK)
{
"data": {
"access_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6...",
"token_type": "Bearer",
"expires_in": 300,
"act": {
"sub": "service_role"
},
"user": {
"id": "b2f4c3a1-7788-4e89-a5c2-98e3b1234567",
"email": "user@example.com",
"role": "authenticated"
}
}
}
TypeScript SDK#
Utilice authAdmin.impersonate() con un cliente Aurabase configurado con la clave service_role:
import { createClient } from '@aurabase/aurabase-js'
const aura = createClient(process.env.AURABASE_URL!, process.env.AURABASE_SERVICE_ROLE_KEY!)
// Genera un token de suplantación durante 5 minutos
const { data, error } = await aura.authAdmin.impersonate('b2f4c3a1-7788-4e89-a5c2-98e3b1234567', {
reason: 'Reproducing issue reported on dashboard',
ttlSeconds: 300,
})
if (error) {
console.error('Failed to impersonate:', error.message)
} else {
console.log('Impersonation token:', data.access_token)
console.log('Token expires in:', data.expires_in, 'seconds')
// Cree un cliente de usuario efímero para ejecutar consultas como este usuario
const userClient = createClient(process.env.AURABASE_URL!, process.env.AURABASE_ANON_KEY!, {
accessToken: data.access_token,
})
// Las consultas ahora se ejecutarán en el contexto RLS del usuario objetivo.
const { data: posts } = await userClient.from('posts').select('*')
}
Cuentas privilegiadas y registros de auditoría#
Protegiendo cuentas privilegiadas
Las cuentas de destino que poseen roles administrativos (como role = 'admin', role = 'owner' o app_metadata.roles que contienen 'admin') representan objetivos de alto valor. Para evitar la elevación accidental de privilegios:
- Debes pasar explícitamente
allow_privileged: true. - Se debe proporcionar una cadena
reasonque no esté vacía. - Si cualquiera de las comprobaciones falla, el backend rechaza la solicitud con
403 Forbidden.
Registro de auditoría de seguridad
Cada evento de suplantación se inserta en la tabla auth_audit_log del inquilino:
- Acción:
admin_impersonation - ID de usuario: ID del usuario objetivo
- Metadatos: objeto JSON que contiene
{ "actor": "...", "reason": "...", "ttl_seconds": 300, "privileged": false }
Este rastro es visible en Studio › Autenticación › Registros de auditoría y se puede reenviar a herramientas SIEM a través de drenajes de bases de datos.