光环标志
光环基地文档
文档›指南›User impersonation

用户模拟

代表任何用户提供支持和调试，无需询问其密码。限制为 10 分钟，并在安全日志中经过严格审核。

5分钟 读取·级别 中间·修改于 2026年10月26日
自此翻译以来，英文来源已发生变化。某些信息可能已过时。
该页面已自动翻译。英文版具有权威性。
#
概述

什么是冒充？

用户模拟允许管理员或支持工程师生成充当特定用户的短期不记名令牌。这样可以在不请求凭据的情况下重现客户错误、检查 RLS 策略权限或排除数据问题。

Aurabase 中的模拟保证了三个基本安全原则：

  1. 生命周期短：模拟令牌的有效期为 1 到 600 秒（最长 10 分钟，默认 300 秒）。它们从不包含刷新令牌。
  2. 显式参与者归属：颁发的访问令牌携带标准 RFC 8693 act 声明，指示谁发起了会话。
  3. 发布前审核：在生成令牌之前，操作会记录在 auth_audit_log 中，其中包括参与者、原因、持续时间和目标用户。如果日志插入失败，则不会颁发令牌。
#
代币索赔

RFC 8693 法案声明结构

模拟令牌使用项目的活动 ES256 密钥进行签名，并符合标准用户访问令牌格式，并带有附加的 act （参与者）对象：

解码后的 JWT 有效负载json
{
  "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：被模拟的用户的身份。 Postgres RLS (auth.uid()) 计算为此值。
  • act.sub：生成令牌的操作员的身份（例如控制台用户 ID 或 service_role）。
#
HTTP API

管理端点

模拟需要通过 service_role 密钥或具有 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
  }'

请求正文

领域类型必填描述
reason字符串选修的安全日志中记录的理由。 特权目标帐户需要 (admin/owner)。
ttl_seconds数量可选令牌生命周期（以秒为单位）（1 到 600，默认 300）。
allow_privileged布尔值可选如果目标用户具有 admin 或 owner 角色，则必须设置为 true。

响应（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

将 authAdmin.impersonate() 与配置有 service_role 密钥的 Aurabase 客户端结合使用：

admin-debug.tstypescript
import { createClient } from '@aurabase/aurabase-js'

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

// 生成 5 分钟的模拟令牌
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')

  // 创建一个临时用户客户端以作为该用户运行查询
  const userClient = createClient(process.env.AURABASE_URL!, process.env.AURABASE_ANON_KEY!, {
    accessToken: data.access_token,
  })

  // 查询现在将在目标用户的 RLS 上下文下执行
  const { data: posts } = await userClient.from('posts').select('*')
}
#
安全性

特权帐户和审核日志

保护特权帐户

具有管理角色的目标帐户（例如 role = 'admin'、 role = 'owner'或包含 'admin'的 app_metadata.roles ）代表高价值目标。为防止意外特权提升：

  1. 您必须显式传递 allow_privileged: true。
  2. 必须提供非空 reason 字符串。
  3. 如果任一检查失败，后端将使用 403 Forbidden拒绝请求。

安全审计日志

每个模拟事件都会插入到租户的 auth_audit_log 表中：

  • 操作: admin_impersonation
  • 用户 ID：目标用户的 ID
  • 元数据：包含 { "actor": "...", "reason": "...", "ttl_seconds": 300, "privileged": false } 的 JSON 对象

此跟踪在 Studio 中可见 › 身份验证 › 审核日志，并且可以通过数据库引流转发到 SIEM 工具。

最后更新· 2026年10月26日