Saltar al contenido
Logotipo de Aurabase
aurabase

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.

Guía práctica5 min leerNivel intermedioRevisado el 26 oct 2026

Esta página fue traducida automáticamente. La versión en inglés es autorizada.

¿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:

  1. 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.
  2. Atribución explícita del actor: el token de acceso emitido lleva el reclamo estándar RFC 8693 act que indica quién inició la sesión.
  3. Auditoría antes de la emisión: la acción se registra en auth_audit_log con 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:

Carga útil JWT decodificadajson
{
  "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 o service_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.

Terminalbash
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

campoTipoRequeridoDescripción
reasoncuerdaOpcionalJustificación registrada en registros de seguridad. Requerido para cuentas de destino privilegiadas (admin/owner).
ttl_secondsnumeroOpcionalDuración del token en segundos (de 1 a 600, por defecto 300).
allow_privilegedbooleanoOpcionalDebe establecerse en true si el usuario de destino tiene una función admin o owner.

Respuesta (200 OK)

json
{
  "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:

admin-debug.tstypescript
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:

  1. Debes pasar explícitamente allow_privileged: true.
  2. Se debe proporcionar una cadena reason que no esté vacía.
  3. 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.