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.
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:
- 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.
- Attribuzione esplicita dell'attore: il token di accesso emesso porta l'attestazione standard RFC 8693
actche indica chi ha avviato la sessione. - Audit prima dell'emissione: l'azione viene registrata in
auth_audit_logcon 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:
{
"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 oservice_role).
Endpoint amministrativo#
La rappresentazione richiede l'autorizzazione dell'amministratore tramite una chiave service_role o un operatore con il ruolo 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
}'
Richiedi corpo
| Campo | Digitare | Obbligatorio | Descrizione |
|---|---|---|---|
reason | stringa | Opzionale | Giustificazione registrata nei registri di sicurezza. Obbligatorio per gli account di destinazione privilegiati (admin/owner). |
ttl_seconds | numero | Facoltativo | Durata del token in secondi (da 1 a 600, predefinito 300). |
allow_privileged | booleano | Facoltativo | Deve essere impostato su true se l'utente di destinazione ha un ruolo admin o owner. |
Risposta (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#
Utilizza authAdmin.impersonate() con un client Aurabase configurato con la chiave service_role:
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:
- È necessario passare esplicitamente
allow_privileged: true. - È necessario fornire una stringa
reasonnon vuota. - 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.