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）
パターン	関数コンポーネント、カスタムフック、Context API
Node.js	>= 18.12.0

---

概要

このスキルは、ReactJS シングルページアプリケーションに完全な認証フローを追加します。Ping Identity DaVinci Client（@forgerock/davinci-client）を使って、PingOne DaVinciに対してユーザーを認証します。

DaVinci と Journey の違い： DaVinci はオーケストレーションサーバーとしてPingOneを使用します（PingAM/AIC ではありません）。@forgerock/journey-client ではなく、@forgerock/davinci-client パッケージを使用します。DaVinci ではコールバックの代わりにコレクターを使用し、ステップタイプの代わりにノードのステータス値（continue、success、error）を使用します。

実装内容は次のとおりです。

• OIDC 設定による DaVinci クライアントの初期化
• ステップごとの認証フローを管理するカスタム React フック（useDavinci）
• 各コレクタータイプ専用の React コンポーネントによる動的なコレクターのレンダリング
• コレクターのカテゴリ：SingleValueCollector、ActionCollector、ObjectValueCollector、MultiValueCollector、NoValueCollector
• FlowCollector によるフローのナビゲーションと、SubmitCollector によるフォームの送信
• React Router による保護されたルートの処理
• コンテキストベースの認証状態管理
• ログインおよびログアウトのフロー
• OIDC userinfo によるユーザープロフィールの表示
• 成功、エラー、失敗の処理

ユースケース

1. サンプルアプリケーション — PingOne DaVinci で DaVinci SDK がどのように動作するかを示す、テーマを適用した完全な ReactJS アプリを一から構築します。SDK 統合ファイル一式に加え、ナビゲーション、スタイル付きビュー、ユーザープロフィールページ、保護されたコンテンツを備えた完全な UI を含みます。
2. 既存アプリケーションへの統合 — 既存の ReactJS SPA に DaVinci SDK を統合して認証機能を追加します。エージェントは SDK 統合ファイル（定数、コンテキスト、フック、フォーム、コレクター）のみを生成し、既存のルーターとレイアウトへの組み込み方法をユーザーに案内します。

---

前提条件

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

---

必須の設定

エージェントへの指示： ファイルを生成する前に、以下の値をユーザーから収集してください。 すべての required パラメーターを、最初にまとめて一度のプロンプトで尋ねてください。オプションのパラメーターについては、 デフォルト値を示したうえで、変更するかどうかを尋ねてください。すべての 必須パラメーターに空でない値が入力されるまで、ステップ 1 に進まないでください。

収集するパラメーター

パラメーター	必須	デフォルト	説明
clientId	はい	—	このウェブアプリ用に PingOne で登録した 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 フックを作成する

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. props としてコレクターオブジェクトと更新関数／フロー関数を受け取る
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 template を参照してください。

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 template を参照してください。

---

ステップ 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/davinci-client ではなく @forgerock/journey-client を使用する	DaVinci は別のパッケージを使用します。@forgerock/davinci-client をインストールしてください
openid スコープがない	必ず openid を含めてください。OIDC トークン交換に必要です
ディスカバリーエンドポイントが間違っている	/.well-known/openid-configuration で終わり、PingOne 環境を指している必要があります
コレクターを指定せずに update() を呼び出す	davinciClient.update(collector) では、引数としてコレクターオブジェクトが必要です
FlowCollector で flow() を呼び出さない	フローのナビゲーションには next() ではなく、davinciClient.flow({ action: collector.output.key }) が必要です
認証情報をハードコードする	環境変数を使用してください。シークレットをコミットしないでください
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 相当スキル