用途
该技能是 Oracle IDCS + Better Auth 搭建工作的入口技能，属于认证基础层，负责 Oracle 适配器、OIDC 配置、可信来源、回调 URL、provider 启动引导，以及跨应用一致性等主题。
它被明确定位为“路由器，而非深度实现指南”：用于诊断问题所在层，再交接给合适的技能，而不是直接给出完整实现细节。
问题归属决策
- 问题位于认证基础（安装、配置、引导）→ 留在本技能。
- 问题位于 Fastify 运行时请求/会话处理 → 转至 fastify-better-auth-bridge。
- 问题位于登录后成员关系、groups 或 org_members 写入 → 转至 oracle-idcs-org-provisioning。
- 用户不确定 bug 在哪一层 → 先用本技能核对安装检查清单。
基础验证顺序
诊断安装问题时，需按以下顺序验证，后续项依赖前面项：
- 数据库中存在 Oracle 适配器和 Better Auth 表。
- IDCS 机密应用使用正确的回调 URL。
- scope 包含
openid,email,profile,urn:opc:idm:__myscopes__。 - 可信来源和 cookie 属性与已部署应用拓扑匹配。
- 在编辑数据库管理的 provider 设置之前，环境配置即可冷启动认证。
- 环境到数据库的引导是幂等的，且从不覆盖已有的 provider 行。
不明显但重要的安装规则
环境优先引导： 在数据库中不存在 provider 行之前，认证必须仅凭环境变量即可工作。provider 行用于运维可见性，而不是用于冷启动。若顺序颠倒，首次部署在任何数据库 seed 运行前认证就会中断。
共享构建块： Oracle 适配器、cookie 规则、IDCS profile 映射器和会话钩子行为必须在 Fastify 与 Next.js 应用之间共享。二者出现分歧会导致难以追踪的 token/session 不一致。
命名稳定： 当代码库已经在使用 IDCS 与 OCI_IAM_* 环境变量命名时，应保持。混合命名方案（例如引入 ORACLE_* 变量）会破坏脚本并使环境变量矩阵混乱。
回调 URL 失败模式： 错误的回调 URL 表现像 OAuth 流程成功（IDCS 重定向回来），但本地会话创建在此后立即失败。若登录看似“完成”但用户未通过认证，应优先检查此项，再调试其他内容。
常见陷阱
| 症状 | 可能原因 |
|---|---|
token 中没有 groups 声明 |
缺少 urn:opc:idm:__myscopes__ scope |
| OAuth 成功，会话失败 | IDCS 应用配置中的回调 URL 错误 |
| 部署时 provider 行被清除 | 引导逻辑不幂等 |
| 本地认证正常，生产失败 | 可信来源缺少生产域名 |
脚本
# 校验所有必需环境变量已设置
node scripts/validate-idcs-env.js
# 打印完整安装检查清单及当前状态
node scripts/print-auth-checklist.js
参数
$ARGUMENTS：可选，指定安装关注点。
示例：/oracle-idcs-better-auth-setup callback-url
示例：/oracle-idcs-better-auth-setup trusted-origins
若留空：审计完整的共享认证安装流程。