Suplantación de usuario

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.

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 o service_role).

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

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"
    }
  }
}

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('*')
}

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.