Vai al contenuto
Logo Aurabase
aurabase

Rappresentazione dell'utente

Agisci per conto di qualsiasi utente per supporto e debug senza chiedere la password. Limitato a 10 minuti, rigorosamente controllato nei registri di sicurezza.

Guida pratica5 min lettoLivello intermedioRevisionato il 26 ott 2026

Questa pagina è stata tradotta automaticamente. Fa fede la versione inglese.

Cos'è l'imitazione?#

La rappresentazione dell'utente consente a un amministratore o a un tecnico del supporto di generare un token al portatore di breve durata che funge da utente specifico. Ciò consente di riprodurre i bug dei clienti, controllare le autorizzazioni dei criteri RLS o risolvere problemi relativi ai dati senza richiedere credenziali.

La rappresentazione in Aurabase garantisce tre principi fondamentali di sicurezza:

  1. Durata breve: i token di rappresentazione sono validi tra 1 e 600 secondi (10 minuti massimo, predefinito 300 secondi). Non includono mai un token di aggiornamento.
  2. Attribuzione esplicita dell'attore: il token di accesso emesso porta l'attestazione standard RFC 8693 act che indica chi ha avviato la sessione.
  3. Audit prima dell'emissione: l'azione viene registrata in auth_audit_log con l'attore, il motivo, la durata e l'utente di destinazione prima che il token venga generato. Se l'inserimento del log fallisce, non viene emesso alcun token.

Struttura delle rivendicazioni dell'atto RFC 8693#

Un token di rappresentazione viene firmato con la chiave ES256 attiva del progetto ed è conforme al formato standard del token di accesso utente, con un oggetto act (attore) aggiuntivo:

Carico utile decodificato JWTjson
{
  "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: l'identità dell'utente rappresentato. Postgres RLS (auth.uid()) restituisce questo valore.
  • act.sub: l'identità dell'operatore che ha generato il token (ad esempio l'ID utente della console o service_role).

Endpoint amministrativo#

La rappresentazione richiede l'autorizzazione dell'amministratore tramite una chiave service_role o un operatore con il ruolo 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
  }'

Richiedi corpo

CampoDigitareObbligatorioDescrizione
reasonstringaOpzionaleGiustificazione registrata nei registri di sicurezza. Obbligatorio per gli account di destinazione privilegiati (admin/owner).
ttl_secondsnumeroFacoltativoDurata del token in secondi (da 1 a 600, predefinito 300).
allow_privilegedbooleanoFacoltativoDeve essere impostato su true se l'utente di destinazione ha un ruolo admin o owner.

Risposta (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#

Utilizza authAdmin.impersonate() con un client Aurabase configurato con la chiave 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 di rappresentazione per 5 minuti
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')

  // Crea un client utente temporaneo per eseguire query come questo utente
  const userClient = createClient(process.env.AURABASE_URL!, process.env.AURABASE_ANON_KEY!, {
    accessToken: data.access_token,
  })

  // Le query verranno ora eseguite nel contesto RLS dell'utente di destinazione
  const { data: posts } = await userClient.from('posts').select('*')
}

Account privilegiati e registri di controllo#

Protezione degli account privilegiati

Gli account di destinazione che possiedono ruoli amministrativi (come role = 'admin', role = 'owner' o app_metadata.roles contenente 'admin') rappresentano destinazioni di alto valore. Per evitare l'elevazione accidentale dei privilegi:

  1. È necessario passare esplicitamente allow_privileged: true.
  2. È necessario fornire una stringa reason non vuota.
  3. Se uno dei controlli fallisce, il backend rifiuta la richiesta con 403 Forbidden.

Registro di controllo della sicurezza

Ogni evento di rappresentazione viene inserito nella tabella auth_audit_log del tenant:

  • Azione: admin_impersonation
  • ID utente: ID dell'utente di destinazione
  • Metadati: oggetto JSON contenente { "actor": "...", "reason": "...", "ttl_seconds": 300, "privileged": false }

Questo percorso è visibile in Studio › Autenticazione › Log di controllo e può essere inoltrato agli strumenti SIEM tramite svuotamenti di database.