Representação do usuário

A personificação do usuário permite que um administrador ou engenheiro de suporte gere um token de portador de curta duração que atue como um usuário específico. Isso permite reproduzir bugs do cliente, verificar permissões de política RLS ou solucionar problemas de dados sem solicitar credenciais.

A representação em Aurabase garante três princípios fundamentais de segurança:

1. Vida útil curta: Os tokens de representação são válidos entre 1 e 600 segundos (10 minutos no máximo, padrão 300 segundos). Eles nunca incluem um token de atualização.
2. Atribuição explícita de ator: O token de acesso emitido carrega a declaração padrão RFC 8693 act indicando quem iniciou a sessão.
3. Auditoria antes da emissão: a ação é registrada em auth_audit_log com o ator, motivo, duração e usuário de destino antes de o token ser gerado. Se a inserção do log falhar, nenhum token será emitido.

Um token de representação é assinado com a chave ES256 ativa do projeto e está em conformidade com o formato padrão do token de acesso do usuário, com um objeto act (ator) 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: a identidade do usuário que está sendo representado. Postgres RLS (auth.uid()) avalia este valor.
• act.sub: A identidade do operador que gerou o token (por exemplo, ID do usuário do console ou service_role).

A representação requer autorização do administrador por meio de uma chave service_role ou de um operador com a função 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
  }'

Solicitar corpo

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

Use authAdmin.impersonate() com um cliente Aurabase configurado com a chave service_role:

import { createClient } from '@aurabase/aurabase-js'

const aura = createClient(process.env.AURABASE_URL!, process.env.AURABASE_SERVICE_ROLE_KEY!)

// Gere um token de representação por 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')

  // Crie um cliente de usuário efêmero para executar consultas como este usuário
  const userClient = createClient(process.env.AURABASE_URL!, process.env.AURABASE_ANON_KEY!, {
    accessToken: data.access_token,
  })

  // As consultas agora serão executadas no contexto RLS do usuário de destino
  const { data: posts } = await userClient.from('posts').select('*')
}

Protegendo contas privilegiadas

As contas de destino que possuem funções administrativas (como role = 'admin', role = 'owner' ou app_metadata.roles contendo 'admin') representam destinos de alto valor. Para evitar a elevação acidental de privilégios:

1. Você deve passar explicitamente allow_privileged: true.
2. Uma string reason não vazia deve ser fornecida.
3. Se alguma das verificações falhar, o back-end rejeitará a solicitação com 403 Forbidden.

Registro de auditoria de segurança

Cada evento de representação é inserido na tabela auth_audit_log do locatário:

• Ação: admin_impersonation
• ID do usuário: ID do usuário alvo
• Metadados: objeto JSON contendo { "actor": "...", "reason": "...", "ttl_seconds": 300, "privileged": false }

Essa trilha é visível em Studio › Autenticação › Logs de auditoria e pode ser encaminhada para ferramentas SIEM por meio de drenagem de banco de dados.