ping-orchestration-reactjs-davinci-sdk

使用 Ping Orchestration JavaScript SDK（DaVinci）进行 ReactJS 身份验证

使用 Ping Orchestration JavaScript SDK（DaVinci），在 ReactJS 单页应用中搭建完整的身份验证流程。

---

元数据

字段	值
语言	JavaScript (JSX)
框架	React 18+、React Router 6+、Vite
SDK	Ping Identity DaVinci Client (@forgerock/davinci-client)
模式	函数组件、自定义 Hook、Context API
Node.js	>= 18.12.0

---

概述

此技能可为 ReactJS 单页应用添加完整的身份验证流程。它使用 Ping Identity DaVinci Client（@forgerock/davinci-client）对用户进行 PingOne DaVinci 身份验证。

**DaVinci 与 Journey 的区别：**DaVinci 使用 PingOne 作为编排服务（而非 PingAM/AIC）。它使用 @forgerock/davinci-client 包（而非 @forgerock/journey-client）。DaVinci 使用 Collectors，而非 Callbacks，并使用节点状态值（continue、success、error），而非步骤类型。

实现涵盖：

• 使用 OIDC 配置初始化 DaVinci 客户端
• 用于管理分步身份验证流程的自定义 React Hook（useDavinci）
• 使用专用 React 组件动态渲染各类 Collector
• Collector 类别：SingleValueCollector、ActionCollector、ObjectValueCollector、MultiValueCollector、NoValueCollector
• 通过 FlowCollector 导航流程，并通过 SubmitCollector 提交表单
• 使用 React Router 处理受保护路由
• 基于 Context 的身份验证状态管理
• 登录和登出流程
• 通过 OIDC userinfo 显示用户资料
• 成功、错误和失败处理

使用场景

1. 示例应用 — 从头构建完整、主题化的 ReactJS 应用，演示 DaVinci SDK 如何与 PingOne DaVinci 配合使用。这包括所有 SDK 集成文件，以及带导航、样式化视图、用户资料页和受保护内容的完整 UI。
2. 集成到现有应用 — 将 DaVinci SDK 集成到现有 ReactJS SPA 中以添加身份验证。Agent 应仅生成 SDK 集成文件（常量、Context、Hook、表单、Collectors），并指导用户如何将其接入现有路由器和布局。

---

前提条件

1. npm 依赖项

在 React 项目中安装以下包：

npm install @forgerock/davinci-client react react-dom react-router-dom

用于扩展功能的可选依赖项：

# PingOne Protect integration
npm install @forgerock/protect

# OIDC client for token management post-authentication
npm install @forgerock/oidc-client

完整示例请参阅 package.json 模板。

2. Vite 配置

此技能使用 Vite 作为构建工具。推荐配置请参阅 vite.config.js 模板。

npm install --save-dev vite @vitejs/plugin-react

3. 环境变量

在项目根目录中创建 .env 文件。请参阅 .env 模板。

另外，添加 .gitignore，避免将机密和构建产物纳入版本控制。请参阅 .gitignore 模板。

VITE_CLIENT_ID=your-client-id
VITE_DISCOVERY_ENDPOINT=https://auth.pingone.com/<envId>/as/.well-known/openid-configuration
VITE_REDIRECT_URI=http://localhost:5173/callback
VITE_SCOPE=openid email profile

---

必需配置

**Agent 指令：**生成任何文件之前，先向用户收集以下值。 一次性询问所有 required 参数。对于可选参数，显示默认值并询问用户是否要覆盖。 只有在每个必需参数都具有非空值后，才能继续执行步骤 1。

需要收集的参数

参数	必需	默认值	描述
clientId	是	—	在 PingOne 中为此 Web 应用注册的 OAuth 2.0 客户端 ID
serverConfig.wellknown	是	—	PingOne 提供的完整 OIDC 发现端点 URL
scope	是	openid email profile	以空格分隔的 OAuth 2.0 作用域
redirectUri	是	http://localhost:5173/callback	OAuth 2.0 重定向 URI

建议的提示词

Before I generate the files, I need a few details about your PingOne DaVinci setup:

1. Client ID           — What is the OAuth 2.0 Client ID for this web app?
                         (From your PingOne OIDC Web App configuration)
2. Well-Known URL      — What is the OIDC discovery endpoint?
                         e.g. https://auth.pingone.com/<envId>/as/.well-known/openid-configuration
3. Scopes              — Which OAuth 2.0 scopes? (default: openid email profile)
4. Redirect URI        — What is the redirect URI? (default: http://localhost:5173/callback)

验证规则

• serverConfig.wellknown 必须以 /.well-known/openid-configuration 结尾。
• clientId 不能为空。
• redirectUri 必须是有效的 URL。
• 如果 scope 不包含 openid，则自动将其添加到开头并向用户发出警告。

---

实现步骤

步骤 1 — 创建常量

创建 constants.js。请参阅 constants.js 模板。

export const DAVINCI_CONFIG = {
  clientId: import.meta.env.VITE_CLIENT_ID,
  serverConfig: {
    wellknown: import.meta.env.VITE_DISCOVERY_ENDPOINT,
  },
  scope: import.meta.env.VITE_SCOPE,
  redirectUri: import.meta.env.VITE_REDIRECT_URI,
};

有关所有配置选项，请参阅 SDK 包参考 中的 @forgerock/davinci-client 部分。

---

步骤 2 — 创建 DaVinci Hook

创建 use-davinci.hook.js。请参阅 use-davinci.hook.js 模板。

主要职责：

• 通过 davinci({ config }) 初始化 DaVinci 客户端
• 管理节点状态（continue、success、error、start）
• 提供 getClient()、getCollectors()、update()、flow()、next() 方法
• 处理流程导航和表单提交

---

步骤 3 — 创建表单组件

创建 form.jsx。请参阅 form.jsx 模板。

表单组件会将每个收集器分发给其专用的 React 组件：

function mapCollectorsToComponents(davinciClient, collectors, submitForm) {
    return collectors.map((collector) => {
        switch (collector.type) {
            case 'TextCollector': return <TextCollector key={collector.id} collector={collector} updater={davinciClient.update(collector)} />;
            case 'PasswordCollector': return <PasswordCollector key={collector.id} collector={collector} updater={davinciClient.update(collector)} />;
            case 'SubmitCollector': return <SubmitButton key={collector.id} collector={collector} submitForm={submitForm} />;
            case 'FlowCollector': return <FlowButton key={collector.id} collector={collector} startFlow={davinciClient.flow({ action: collector.output.key })} />;
            // ... more collectors
        }
    });
}

有关支持的收集器实现的完整列表，请参阅此技能的 assets/ 目录中的收集器模板文件。

步骤 4 — 创建收集器组件

为每种收集器类型分别创建 React 组件文件。所有模板请参见 assets/ 目录。

Ping JavaScript DaVinci SDK 支持的所有收集器类型：

单值收集器：

收集器类型	组件	类别	描述
TextCollector	TextCollector	SingleValueCollector	文本输入（用户名、电子邮件）
PasswordCollector	PasswordCollector	SingleValueCollector	安全密码输入
SingleSelectCollector	SingleSelectCollector	SingleValueCollector	下拉列表／单选项

经过验证的收集器：

收集器类型	组件	类别	描述
ValidatedTextCollector	TextCollector	ValidatedSingleValueCollector	带验证规则的文本输入

操作收集器：

收集器类型	组件	类别	描述
SubmitCollector	SubmitButton	ActionCollector	表单提交按钮
FlowCollector	FlowButton	ActionCollector	工作流导航按钮／链接
IdpCollector	SocialLoginButton	ActionCollector	社交登录（Google、Facebook、Apple）

多值收集器：

收集器类型	组件	类别	描述
MultiSelectCollector	MultiSelectCollector	MultiValueCollector	多选复选框

对象值收集器：

收集器类型	组件	类别	描述
DeviceRegistrationCollector	DeviceRegistration	ObjectValueCollector	MFA 设备注册
DeviceAuthenticationCollector	DeviceAuthentication	ObjectValueCollector	MFA 设备身份验证
PhoneNumberCollector	PhoneNumber	ObjectValueCollector	电话号码输入

无值／只读收集器：

收集器类型	组件	类别	描述
ReadOnlyCollector	ReadOnly	NoValueCollector	静态文本／标签显示

自动前进收集器：

收集器类型	组件	类别	描述
ProtectCollector	Protect	SingleValueAutoCollector	PingOne Protect 风险信号
FidoRegistrationCollector	FidoRegistration	ObjectValueAutoCollector	FIDO2 通行密钥／安全密钥注册
FidoAuthenticationCollector	FidoAuthentication	ObjectValueAutoCollector	FIDO2 通行密钥／安全密钥身份验证

每个收集器组件都遵循以下模式：

1. 接收 收集器对象以及作为属性传入的更新器／工作流函数
2. 渲染 适当的 HTML/React 控件
3. 对于值收集器，使用用户输入调用更新器：updater(value)
4. 对于 FlowCollector，调用工作流函数：startFlow() 会导航到新的工作流
5. 对于 SubmitCollector，调用 submitForm()：前进到下一个节点

关键 API 方法：

• davinciClient.update(collector) — 返回值收集器的更新器函数
• davinciClient.flow({ action: collector.output.key }) — 返回用于启动新工作流的函数
• davinciClient.next() — 提交当前节点并前进到下一个节点
• davinciClient.validate(collector) — 返回经过验证的收集器的验证器函数

---

步骤 5 — 创建登录页面

创建 login.jsx。请参见 login.jsx 模板。

export default function Login() {
    const { davinciClient, clientInfo, collectors, submitForm, startFlow, error } = useDavinci();

    if (!clientInfo || clientInfo.status === 'start') return <p>Loading...</p>;
    if (clientInfo.status === 'success') return <Navigate to="/home" />;

    return (
        <form onSubmit={(e) => { e.preventDefault(); submitForm(); }}>
            <h2>{clientInfo.name}</h2>
            {error && <div className="error">{error.message}</div>}
            <DaVinciForm davinciClient={davinciClient} collectors={collectors} submitForm={submitForm} />
        </form>
    );
}

---

步骤 6 — 创建 OAuth 回调页面

创建 callback.jsx。请参见 callback.jsx 模板。

---

步骤 7 — 配置导航

<BrowserRouter>
    <Routes>
        <Route path="/" element={<Login />} />
        <Route path="/callback" element={<Callback />} />
        <Route path="/home" element={<ProtectedRoute><Home /></ProtectedRoute>} />
    </Routes>
</BrowserRouter>

---

脚手架脚本

如需快速设置，请使用脚手架脚本将所有模板文件复制到项目中：

chmod +x scripts/scaffold_auth.sh
./scripts/scaffold_auth.sh \
    --target-dir src

详情请参阅 scaffold_auth.sh。

---

常见错误

错误	修正方法
使用 @forgerock/journey-client，而不是 @forgerock/davinci-client	DaVinci 使用单独的程序包 — 安装 @forgerock/davinci-client
缺少 openid 范围	始终包含 openid — OIDC 令牌交换必需
发现端点错误	必须以 /.well-known/openid-configuration 结尾，并指向你的 PingOne 环境
未提供收集器就调用 update()	davinciClient.update(collector) 要求将收集器对象作为参数
未为 FlowCollector 调用 flow()	Flow 导航需要使用 davinciClient.flow({ action: collector.output.key })，而不是 next()
硬编码凭据	使用环境变量 — 切勿提交机密信息
未处理 error 状态	检查 clientInfo.status === 'error'，并显示 davinciClient.getError() 返回的错误消息
混淆收集器类别	检查 collector.category（SingleValueCollector、ActionCollector 等），以确定如何处理每个收集器

---

参考文档

• SDK 程序包参考 — @forgerock/davinci-client、@forgerock/oidc-client 和可选附加组件的程序包选择指南
• OIDC 集中式参考 — 完整的 @forgerock/oidc-client API：授权、令牌交换、用户信息、注销、存储
• 收集器实现 — 请参阅 assets/ 中的模板文件（例如 text.jsx.template、password.jsx.template、fido-registration.jsx.template、social-login-button.jsx.template）

---

相关技能

• ping-orchestration-javascript-sdk — JavaScript 总览技能（路由 Journey/DaVinci/OIDC；DaVinci 流程委托至此）
• ping-orchestration-reactjs-journey-sdk — 使用 Journey 模块进行 ReactJS 身份验证（适用于 PingOne AIC/PingAM）
• ping-orchestration-android-sdk — Android（Kotlin/Jetpack Compose）版 DaVinci 对应技能
• ping-orchestration-ios-sdk — iOS（Swift/SwiftUI）版 DaVinci 对应技能