该技能用于在 ReactJS 单页应用中搭建基于 Ping Orchestration JavaScript SDK(DaVinci)的认证流程,通过 @forgerock/davinci-client 包让用户针对 PingOne DaVinci 进行身份认证。文档明确指出 DaVinci 与 Journey 的差异:DaVinci 使用 PingOne 作为编排服务器(而非 PingAM/AIC),使用 @forgerock/davinci-client 包(而非 @forgerock/journey-client),用 Collectors 代替 Callbacks,并用 node 状态值(continue、success、error)代替 step types。
主要能力与实现范围:使用 OIDC 配置初始化 DaVinci 客户端;提供自定义 React 钩子 useDavinci 来管理逐步认证流程;按 collector 类型动态渲染专用 React 组件;支持 FlowCollector 的流程导航与 SubmitCollector 的表单提交;通过 React Router 处理受保护路由;使用 Context API 管理认证状态;包含登录与登出流程;通过 OIDC userinfo 展示用户资料;并处理成功、错误与失败状态。
适用场景:一是示例应用,从零构建完整、可主题化的 ReactJS 应用以演示 DaVinci SDK 与 PingOne DaVinci 的配合,包含全部 SDK 集成文件及带导航、样式视图、用户资料页与受保护内容的完整 UI;二是已有应用集成,将 DaVinci SDK 接入现有 ReactJS SPA,此时只生成 SDK 集成文件(constants、context、hook、form、collectors),并指导用户将其接入现有路由与布局。
使用方式:需先安装依赖 npm install @forgerock/davinci-client react react-dom react-router-dom,可选依赖 @forgerock/protect(PingOne Protect 集成)与 @forgerock/oidc-client(认证后令牌管理);使用 Vite 构建,npm install --save-dev vite @vitejs/plugin-react;在项目根目录创建 .env 文件,配置 VITE_CLIENT_ID、VITE_DISCOVERY_ENDPOINT、VITE_REDIRECT_URI、VITE_SCOPE 等变量。生成文件前需先收集参数:clientId、serverConfig.wellknown、scope(默认 openid email profile)、redirectUri(默认 http://localhost:5173/callback),其中前四项为必填。校验规则包括 wellknown 必须以 /.well-known/openid-configuration 结尾、clientId 非空、redirectUri 为合法 URL,以及 scope 不含 openid 时自动补充并提示用户。
实现步骤依次为:创建 constants.js 常量;创建 use-davinci.hook.js 钩子(初始化客户端、管理 node 状态、暴露 getClient、getCollectors、update、flow、next 等方法);创建 form.jsx 表单组件,按 collector.type 分发到对应组件;创建各类 collector 组件;创建 login.jsx 登录页;创建 callback.jsx OAuth 回调页;最后接入路由。文档还提供了脚手架脚本 scripts/scaffold_auth.sh,可通过 --target-dir src 快速复制模板文件。
支持的 collector 类别包括:SingleValueCollector(如 TextCollector、PasswordCollector、SingleSelectCollector)、ValidatedSingleValueCollector(ValidatedTextCollector)、ActionCollector(SubmitCollector、FlowCollector、IdpCollector)、MultiValueCollector(MultiSelectCollector)、ObjectValueCollector(DeviceRegistrationCollector、DeviceAuthenticationCollector、PhoneNumberCollector)、NoValueCollector(ReadOnlyCollector)以及自动推进类(ProtectCollector、FidoRegistrationCollector、FidoAuthenticationCollector)。关键 API 方法有 davinciClient.update(collector)、davinciClient.flow({ action: collector.output.key })、davinciClient.next()、davinciClient.validate(collector)。
限制与注意事项:文档要求 Node.js >= 18.12.0,框架为 React 18+、React Router 6+ 与 Vite;应避免误用 @forgerock/journey-client;scope 必须包含 openid;discovery 端点必须正确指向 PingOne 环境;FlowCollector 必须调用 flow() 而非 next();凭据应使用环境变量而非硬编码;需处理 error 状态并展示 davinciClient.getError() 的错误信息;需依据 collector.category 区分处理方式。关于收费、价格、平台支持范围与认证效果,资料未提供相关信息。