Auth0 客户身份平台：从 Tenant 接入到联邦、审计与安全退出

高谷深陵大约 16 分钟约 4764 字

测试环境的登录按钮能够跳到 Auth0，用户输入账号后也能返回应用，生产发布却在回调处不断报 invalid_state 或 unauthorized_client。团队先怀疑 SDK，随后才发现生产 Application 没有登记真实 callback URL，而且应用仍拿测试 tenant 的 issuer 验签。浏览器跳转成功只证明授权链走到了一半；tenant、application、connection、redirect URI、会话和资源端验签必须属于同一套环境，登录才真正闭环。

另一支团队把所有客户放进同一个 Database Connection，再把客户编号写入可由用户修改的 metadata。API 只检查“令牌有效”，没有检查组织成员关系，结果一个合法登录者能够切换客户编号读取别人的数据。Auth0 可以完成认证、联邦和令牌签发，但租户授权仍要由可信属性、Organization membership、API audience 与业务策略共同约束。身份平台减少了自建认证基础设施，不会替应用替代授权设计。

Auth0 客户身份访问链沿 tenant、application、connection、Organization、Actions、token 与日志建立可验证、可回滚的身份链路。高清原图

先把 Tenant、Application 与 Connection 分开

Auth0 是托管客户身份平台，服务端不安装在业务主机上。顶层隔离边界是 tenant：Application、API、Connection、User、Organization、Action、日志和域名配置都归属于某个 tenant。开发、测试与生产若共用 tenant，回调地址、测试用户、社交连接和扩展代码就会互相影响；按软件生命周期拆分 tenant，才能让一次配置推广拥有明确的来源和目标。tenant 名称与部署位置会进入 issuer 和域名契约，创建前应从 Tenant 创建与隔离说明核对位置、命名和不可变约束。

Application 是 OAuth/OIDC client 注册。它保存不可随意替换的 client_id、应用类型、允许的 callback/logout/web origin、grant 和凭据。SPA 与原生应用属于 public client，运行环境无法保守 secret；传统服务端 Web 应用和机器到机器客户端才可能安全持有凭据。API 或 Resource Server 表示令牌面向的资源，identifier 通常成为 audience。只创建 Application 而不定义 API，得到的令牌未必能被业务 API 按预期 audience 接受。

Connection 决定用户从哪里认证，可对应 Auth0 数据库、社交身份源、企业 OIDC/SAML 或无密码入口。Connection 必须显式启用给目标 Application。企业联邦中，Auth0 面向上游 IdP 是 RP/SP，完成上游认证后又面向业务 Application 充当授权服务器。Organization 则表示 B2B 客户、合作伙伴或业务组织，可关联成员、Connection 和组织内角色；它不是另一个 tenant，也不是可以直接拿来访问云资源的凭据池。

在隔离 Tenant 启用第一条登录链

第一次接入应使用可删除的开发 tenant。操作者需要 tenant 管理权限、一个不会指向真实客户的测试账号，以及应用本地回调地址。打开 Auth0 Dashboard 创建 Application 时，先按应用形态选择 SPA、Native、Regular Web Application 或 Machine to Machine；这个选择会改变允许的 grant、凭据处理方式和推荐 SDK。随后在 Application Settings 登记精确 callback 与 logout URL，例如 http://localhost:3000/callback。协议会精确比较 scheme、host、port 与 path，不能用宽泛域名代替逐项登记。

CLI 适合开发者检查当前 tenant 和对象，实际安装入口与可用命令应从 Auth0 CLI 文档获取，并在团队工具清单中固定经过验证的版本。交互式登录会打开浏览器，不适合直接复制到无人值守流水线；CI 应使用专用 M2M Application、最小 Management API scope 和受保护凭据。

# 登录后先确认当前身份和 tenant，再查看应用对象。
auth0 login
auth0 tenants list
auth0 apps list --json

# AUTH0_DOMAIN 只写域名，不带协议和路径。
curl --fail --silent --show-error \
  "https://$AUTH0_DOMAIN/.well-known/openid-configuration"

创建顺序建议固定为 tenant 环境约束、API/audience、Application、Connection 启用关系、callback/logout URL，最后才接 SDK。配置推广可使用 Deploy CLI、Terraform provider 或 Management API，但不要把控制台导出的全部对象直接覆盖生产。尤其是 Deploy CLI 的删除开关可能移除 tenant 资源；先在同结构测试 tenant 查看差异，再由第二位维护者复核删除集合和回滚文件。动态能力、安装方式与参数始终以 Deploy CLI 当前说明为准。

用 Discovery 做第一组正反实验

最小正例不是“看见登录页”，而是证明应用读取到预期 tenant 的 OIDC 元数据。先导出开发 tenant 域名，获取 discovery JSON，检查 issuer、authorization_endpoint、token_endpoint 和 jwks_uri 是否同属预期域名。HTTP 200 只是传输成功；字段一致才说明项目不会把授权请求发往一个 tenant、又从另一个 tenant 获取密钥。

set -eu

curl --fail --silent --show-error \
  "https://$AUTH0_DOMAIN/.well-known/openid-configuration" \
  > auth0-discovery.json

jq -e --arg issuer "https://$AUTH0_DOMAIN/" \
  '.issuer == $issuer and
   (.authorization_endpoint | startswith($issuer)) and
   (.jwks_uri | startswith($issuer))' \
  auth0-discovery.json

正例应让 jq 返回零。反例故意使用一个专门构造且不存在的 tenant 域名，curl --fail 应非零退出；应用启动检查也应拒绝错误 issuer，而不是在 discovery 失败后关闭签名或 audience 校验。

set +e
curl --fail --silent --show-error \
  "https://does-not-exist.example.auth0.com/.well-known/openid-configuration"
status=$?
set -e

test "$status" -ne 0
rm -f auth0-discovery.json

如果错误域名因网络代理、DNS 劫持或自定义错误页意外返回 200，还要解析 JSON 并比较 issuer，不能只依赖状态码。实验结束删除本地响应文件；其中虽不应包含 secret，却会暴露环境域名和端点拓扑，不应长期散落在 CI artifact。

把 OIDC 验签接进真实 API

项目接入的核心是让浏览器或服务端完成 Authorization Code Flow，资源端再独立验证 access token。SPA 与原生应用使用 Authorization Code + PKCE，不放 client secret；服务端 Web 应用把 secret 放进服务端 Secret Store；机器调用使用独立 M2M client 和 Client Credentials Flow。具体框架应从 Auth0 Quickstarts选择，但无论 SDK 怎样包装，资源端都必须校验 signature、issuer、audience、expiry 与业务所需 scope。

下面的 Node.js 骨架使用 jose 从 JWKS 获取公钥。依赖版本应由项目锁文件固定；AUTH0_AUDIENCE 是业务 API identifier，不是 Application 的 client ID。不要把完整 token、JWKS 响应或用户资料打进错误日志。

import { createRemoteJWKSet, jwtVerify } from "jose";

const issuer = `https://${process.env.AUTH0_DOMAIN}/`;
const audience = process.env.AUTH0_AUDIENCE;
const jwks = createRemoteJWKSet(new URL(`${issuer}.well-known/jwks.json`));

export async function authenticate(request, response, next) {
  const value = request.headers.authorization ?? "";
  const token = value.startsWith("Bearer ") ? value.slice(7) : "";

  try {
    const { payload } = await jwtVerify(token, jwks, { issuer, audience });
    request.principal = { subject: payload.sub, scope: payload.scope ?? "" };
    next();
  } catch (error) {
    response.status(401).json({ code: "invalid_access_token" });
  }
}

授权应在认证之后单独执行。例如写订单要求 write:orders，访问某客户数据还要求服务端从可信 membership 映射确认 Organization。ID token 面向客户端登录信息，access token 面向 API；不能把 ID token 当 API 凭据，也不能仅解码 JWT 后相信其 claims。JWKS 缓存要允许密钥轮换，未知 kid 可受控刷新一次，但不能无界重试拖垮身份端点。

让 Connection 与 Organization 表达真实边界

一个 Application 可启用多个 Connection，但“同一邮箱”不等于“同一主体”。数据库、社交与企业 IdP 首次登录可能创建不同 user_id；自动按 email 合并会把未验证邮箱或可被重新分配的地址变成账号接管入口。账号关联必须要求用户同时证明两个身份，记录旧、新主体 ID 与操作人，并让撤销路径可执行。

企业 Connection 需要同时维护两边配置：Auth0 侧的 OIDC/SAML metadata、client credential、attribute mapping 和启用的 Application；上游 IdP 侧的 redirect/ACS、entity/client ID、签名证书与 logout。出现“上游登录成功但 Auth0 拒绝”时，先对照 connection、Application 启用关系、回调、签名与映射，不要直接改用户资料。当前支持的企业身份源与配置入口以 Enterprise Identity Providers为准。

Organization 适合“一位用户可属于多个客户，每个客户可有自己的成员、连接与角色”的 B2B 模型。登录请求带 Organization 标识后，回调仍要验证返回上下文并由服务端检查 membership。业务数据库应保存独立稳定的内部 user key 与 organization key，再映射 Auth0 user_id 和 Organization ID；不要把外部 ID 直接当所有表的永久主键。Organization 的登录方式、可用能力和商业边界会变化，实施时就地核对 Organizations 总览，不要把套餐名称或数量限制固化进架构。

用 Actions 扩展认证而不拖垮认证

Actions 是受支持认证流程中的扩展点，代码发布成版本后还必须绑定到相应 trigger/flow 才会生效。适合的动作包括在 post-login 基于可信数据添加受控 claim、执行风险判断或向审计系统发送最小事件。它不适合承载长事务、批处理或无限等待的外部调用，因为一次外部依赖抖动会占住认证扩展并发，最终把单个下游故障放大为全体用户无法登录。

exports.onExecutePostLogin = async (event, api) => {
  const namespace = "https://claims.example.com";
  const organizationId = event.organization?.id;

  if (organizationId) {
    api.accessToken.setCustomClaim(`${namespace}/organization_id`, organizationId);
  }

  // 不记录 token、secret、完整 profile 或 event.request。
  console.log(JSON.stringify({
    event: "post_login",
    user_id: event.user.user_id,
    client_id: event.client.client_id,
    organization_id: organizationId ?? null,
  }));
};

自定义 claim 使用业务控制的命名空间，只放资源端决策真正需要且体积稳定的信息。大型权限全集应由 API 按主体和租户查询，避免 token 膨胀、权限撤销延迟和日志泄露。Action secret 通过专用 secret 配置注入，代码仓库里只保留变量名；外部请求设置短超时，明确 fail-open 还是 fail-close，并为失败率和延迟建立告警。依赖、运行限制与发布行为从 Actions 文档和依赖限制核对。

遗留 Rules、Hooks 或 Extensions 不应继续成为新设计基线。团队要按官方产品生命周期入口建立清单：每个扩展记录 trigger、输入输出、secret、外部副作用、超时和失败策略，再迁成 Action 或应用侧异步逻辑。不要在正文或运维手册里写死最终移除日期，变更窗口前重新确认状态即可。

用最小 Scope 做第二组正反实验

管理面自动化使用 Management API token，它能读取或修改 tenant 对象，风险远高于普通用户 access token。为日志采集、应用盘点、配置发布分别创建 M2M client，让每个 client 只拥有所需 scope；不要共享一个全权 token。正例使用具备 read:clients 的测试 token，只请求必要字段，并同时保留响应状态与 rate-limit headers。

curl --include --fail --silent --show-error \
  -H "Authorization: Bearer $AUTH0_READ_CLIENTS_TOKEN" \
  "https://$AUTH0_DOMAIN/api/v2/clients?fields=client_id,name,app_type&include_fields=true"

反例换成不具备 read:clients 的可撤销测试 token，预期是 403 和权限不足语义。测试脚本只判断状态与脱敏错误码，不打印 token。若反例返回 200，说明授权 client 或 API grant 过宽，应立即撤销 token、收缩 scope 后重跑，而不是把“能访问”当成功。

status=$(curl --silent --show-error --output auth0-error.json \
  --write-out '%{http_code}' \
  -H "Authorization: Bearer $AUTH0_INSUFFICIENT_SCOPE_TOKEN" \
  "https://$AUTH0_DOMAIN/api/v2/clients")

test "$status" = "403"
jq -e '.error == "insufficient_scope" or .statusCode == 403' auth0-error.json
rm -f auth0-error.json

Management API token、Application secret、Action secret、会话 Cookie、authorization code、refresh token、完整 SAML assertion、密码 hash 和 MFA secret 都不得进入仓库、前端 bundle、截图或普通日志。服务端凭据放入受控 Secret Store 并建立 owner、用途、轮换和撤销记录；浏览器端配置只允许公开的 domain、client ID 与 audience。

从日志证据定位身份故障

身份故障先按层分型。浏览器没有到 Auth0，检查 DNS、代理、TLS 和 authorize URL；Auth0 拒绝请求，检查 tenant log 的事件类型、log_id、client、connection、user ID、request/correlation ID 与错误码；回调后应用拒绝，检查 state/nonce、cookie、issuer、audience、signature、expiry 与 clock；API 返回 403，说明认证可能已成功，应继续看 scope、Organization membership 和业务策略。

Dashboard 适合交互排查，Management API 适合短期拉取，Log Streams 或 checkpoint 消费适合长期留存。tenant logs 不是实时队列，告警窗口要容忍投递和索引延迟。checkpoint 必须按 log_id 推进，不能用事件时间猜测是否完整；消费者处理空页、重复、429、token 过期和本地游标持久化。具体分页与限制从日志 API 指南读取。

curl --fail --silent --show-error \
  -H "Authorization: Bearer $AUTH0_LOG_READER_TOKEN" \
  "https://$AUTH0_DOMAIN/api/v2/logs?take=10" > auth0-logs.json

LAST_LOG_ID=$(jq -r 'last.log_id // empty' auth0-logs.json)
test -n "$LAST_LOG_ID"

curl --fail --silent --show-error \
  -H "Authorization: Bearer $AUTH0_LOG_READER_TOKEN" \
  "https://$AUTH0_DOMAIN/api/v2/logs?from=$LAST_LOG_ID&take=10"
rm -f auth0-logs.json

日志含 IP、用户标识、应用、Connection 和失败原因，应在外送前最小化字段，限制查询角色并设置符合业务与监管要求的保留策略。平台内保留能力随商业配置变化，长期取证不要依赖控制台仍能看到旧事件；从日志保留说明确认目标 tenant 的现实窗口，再设计外送与删除。

把容量、可用性与成本放进同一张预算

Auth0 的请求能力不能压缩成一个“tenant 每秒请求数”。一次登录会访问 authorize、token、JWKS 或 userinfo，还可能触发多个 Actions、外部 API、Management API 和日志投递。容量评审应从用户动作拆出完整调用链，记录每个端点的请求倍数、峰值、外部依赖延迟、失败重试和令牌刷新行为。收到 429 时读取 rate-limit headers，使用带抖动的指数退避和总时限；固定间隔轮询与无界并发会让恢复更慢。

实体数量、API 限制、日志保留、Organization 与扩展能力可能受 tenant 类型、合同和产品阶段影响。上线前分别查询 Rate Limit Policy、Entity Limit Policy和账户内实际 entitlement。预算同时纳入活跃用户计量口径、M2M、日志外送、企业 Connection、扩展执行、短信邮件与支持要求，不在设计文档抄写静态价格或免费额度。

托管服务的高可用不等于应用侧无需设计故障。应用应缓存 JWKS、限制刷新风暴、给身份调用设置总 deadline，并明确“已有会话可继续多久、何时拒绝新登录、何时关闭高风险操作”。多 tenant 提供环境或客户故障隔离，却增加配置漂移、用户迁移、域名、日志和成本；单 tenant 更易统一治理，却扩大配置错误和容量争用的爆炸半径。选择由隔离要求、定制域名、数据位置、客户身份源和团队维护能力共同决定。

清理开发对象并保留可逆回滚

开发实验结束按引用关系清理：先让测试应用停止发起登录，撤销临时 Management API token 和 M2M grant，再解绑 Action、禁用 Connection、删除测试 Organization 成员和用户，最后删除 Application、API 或 tenant。若先删 Connection，仍在测试的应用会得到难以区分的登录失败；若只删 Application 而不撤销凭据，外部 Secret Store 和 CI 仍会保留无主 secret。

生产回滚不能靠“恢复昨天导出的 JSON”概括。每次推广前保存 tenant 配置 revision、目标 tenant、对象差异、凭据变更和不可逆操作清单；callback、Connection、Action 与 API audience 分批变更，并保留旧应用版本可接受的兼容窗口。发生故障时先停止配置写入，恢复上一个 Action 绑定或 Application 设置，撤销新凭据，再用 discovery、真实授权码登录、API 验签和日志关联重新验证。

tenant 删除是最后动作。确认没有活跃用户、有效 client、外部 IdP redirect、custom domain、日志流、支持工单和账单后，再执行平台允许的删除流程；同时删除 DNS、IdP 凭据、Secret Store 条目、IaC state 引用和日志目的地。清理证据至少保留对象 ID、撤销结果、外部依赖核销与审批记录，不保留真实 token 或用户导出。

迁移时先冻结身份主键与会话语义

迁入 Auth0 有批量导入和首次登录自动迁移两类主线。批量导入适合能够形成受支持 profile 和密码 hash 格式的来源；自动迁移通过 Custom Database Connection 在首次登录时调用旧身份库验证密码。两者都要先定义内部 user key、旧主体 ID、Auth0 user_id、Organization membership 和迁移状态的映射。导入 job 成功不代表 MFA、设备、风险历史、会话和 refresh token 已迁移，用户通知与重新 enrollment 必须单独设计。具体 job、格式和限制从 User Migration与 Bulk User Imports核对。

迁出时，普通用户资料导出不等于可复用密码和 MFA secret 导出。密码 hash/MFA secret 涉及资格审查、支持流程和加密交付，也不能保证目标平台接受该格式。现实路线通常是保留一段旧密码验证能力做懒迁移，或导入 profile 后要求重置密码。迁移演练必须覆盖首次与重复登录、forgot-password、多个 Connection、重复邮箱、上游属性变化、错误 issuer/audience、未知 kid、Action 超时、429、MFA 重绑和强制会话失效。

切流采用 canary 或按用户状态路由，旧、新平台日志使用同一 migration correlation ID 关联。业务 API 在双轨期显式接受两套 issuer，但每套 issuer 都绑定自己的 audience、JWKS 与 claim 映射，禁止“接受任意可信签名”。回退窗口内保持旧 IdP、旧用户验证面和失败队列可用；当活跃主体完成迁移、旧 token 超过最大有效期、凭据和回调全部撤销、数据与账单核销完成后，才关闭旧 tenant。这样退出的是一条被证明不再承载身份的链路，而不是一块仍可能签发有效凭据的控制面。