ping-orchestration-reactjs-journey-sdk

Ping Orchestration JavaScript SDK を使用した ReactJS 認証

Ping Orchestration JavaScript SDK（Journey）を使用して、ReactJS のシングルページアプリケーションに完全な認証フローを構築します。

---

メタデータ

項目	値
言語	JavaScript (JSX)
フレームワーク	React 18+, React Router 6+, Vite
SDK	Ping Orchestration JavaScript SDK (@forgerock/journey-client, @forgerock/oidc-client)
パターン	関数コンポーネント、カスタムフック、Context API
Node.js	>= 18.12.0

---

概要

このスキルは、ReactJS のシングルページアプリケーションに完全な認証フローを追加します。Ping Identity Orchestration JavaScript SDK（Journey クライアント）を使用して、PingOne Advanced Identity Cloud（AIC）またはPingAMに対してユーザーを認証します。

この実装では、以下に対応しています。

• OIDC の well-known エンドポイント検出による Journey クライアントの設定
• OAuth 2.0 のトークン交換、更新、取り消しのための OIDC クライアント設定
• 段階的な認証フローを管理するカスタム React フック（useJourney）
• コールバックの種類ごとに専用の React コンポーネントを使用した動的なコールバックのレンダリング
• React Router による保護されたルートの処理
• コンテキストベースの認証状態管理
• ログイン、登録、ログアウトのフロー
• oidcClient.user.info() によるユーザープロファイルの表示（任意の編集 UI 付き）
• 成功、エラー、失敗の処理

ユースケース

1. サンプルアプリケーション — Ping Orchestration JavaScript SDK が PingAM および AIC とどのように連携するかを示す、テーマ設定済みの完全な ReactJS アプリをゼロから構築します。これには、すべての SDK 統合ファイルに加えて、ナビゲーション、スタイル設定済みのビュー、ユーザープロファイルページ、保護されたコンテンツを備えた完全な UI が含まれます。エージェントは package.json、vite.config.js、index.html、CSS スタイルシート、すべてのビュー／コンポーネントを生成します。
2. 既存アプリケーションへの統合 — 既存の ReactJS SPA に Ping Orchestration JavaScript SDK を統合し、認証、ステップアップ認証、または SDK がサポートする任意の Journey／Tree ベースのフローを追加します。エージェントは SDK 統合ファイル（定数、コンテキスト、フック、フォーム、コールバック、保護されたルート）のみを生成し、既存のルーターとレイアウトに組み込む方法を案内します。

---

前提条件

1. npm の依存関係

React プロジェクトに以下のパッケージをインストールします。

npm install @forgerock/journey-client @forgerock/oidc-client react react-dom react-router-dom

追加機能に使用できるオプションの依存関係：

# PingOne Protect integration (threat signals / risk evaluation)
npm install @forgerock/protect

完全な例については、package.json テンプレートを参照してください。

2. Vite の設定

このスキルでは、ビルドツールとして Vite を使用します。推奨設定については、vite.config.js テンプレートを参照してください。

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

3. CORS の設定（PingAM／AIC）

PingAM または AIC のテナントで CORS を設定します。

設定	値
許可するオリジン	https://localhost:8443（またはアプリの URL）
許可するメソッド	GET、POST
許可するヘッダー	Content-Type、X-Requested-With、X-Requested-Platform、Accept-API-Version、Authorization
認証情報を許可	有効

4. OAuth 2.0 クライアントの登録

PingAM／AIC にパブリック（SPA） OAuth クライアントを作成します。

設定	値
クライアントタイプ	パブリック
グラントタイプ	Authorization Code
トークンエンドポイントの認証方式	none
スコープ	openid profile email（最小構成）
リダイレクト URI	アプリのコールバック URL（例：https://localhost:8443/callback.html）
暗黙的な同意	有効

---

必須の設定

エージェントへの指示： ファイルを生成する前に、以下の値をユーザーから収集してください。

ステップ 0 — ユースケースの確認： ユーザーに、サンプルアプリ（package.json、vite.config.js、index.html、CSS、ナビゲーション、スタイル設定済みのビューを含む完全なスキャフォールド）と、既存アプリへの統合（SDK 統合ファイルのみ：定数、コンテキスト、フック、フォーム、コールバック、保護されたルート）のどちらを希望するか尋ねてください。この選択は、後続のステップで生成するファイルに影響します。

すべての必須パラメーターを最初に1つのプロンプトで尋ねてください。オプションのパラメーターについては、デフォルト値を示したうえで、変更を希望するか尋ねてください。すべての必須パラメーターに空でない値が入力されるまで、ステップ 1 に進まないでください。

収集するパラメーター

パラメーター	必須	デフォルト	説明
wellknownUrl	はい	—	OIDC の well-known エンドポイントの完全な URL（例：https://your-tenant.forgeblocks.com/am/oauth2/alpha/.well-known/openid-configuration）
clientId	はい	—	このウェブアプリ用に PingAM / AIC に登録された OAuth 2.0 クライアント ID
scope	はい	openid profile email	リクエストする、スペース区切りの OAuth 2.0 スコープ
redirectUri	いいえ	http://localhost:<appPort>/callback.html	PingAM / AIC に登録された OAuth 2.0 リダイレクト URI
journeyLogin	いいえ	Login	呼び出すログイン Journey/Tree の名前
journeyRegister	いいえ	Registration	呼び出す登録 Journey/Tree の名前
appPort	いいえ	8443	ローカル開発サーバーのポート

プロンプトの例

Before I get started, I want to confirm — are you wanting me to help you create a sample app or
integrate with your existing single-page app?

Before I generate the files, I need a few details about your PingAM / AIC setup:

1. Well-known URL     — What is your OIDC well-known endpoint URL?
                        e.g. https://your-tenant.forgeblocks.com/am/oauth2/alpha/.well-known/openid-configuration
2. Client ID          — What is the OAuth 2.0 Client ID for this web app?
3. Scopes             — Which OAuth 2.0 scopes? (default: openid profile email)
4. Redirect URI       — What is the redirect URI? (default: http://localhost:8443/callback.html)
5. Login Journey      — Which Journey/Tree for login? (default: Login)
6. Register Journey   — Which Journey/Tree for registration? (default: Registration)
7. App Port           — Which port for local dev? (default: 8443)

検証ルール

• wellknownUrl は https:// で始まり、/.well-known/openid-configuration で終わる必要があります。
• clientId は空でない必要があります。
• scope に openid が含まれていない場合は、自動的に先頭に追加し、ユーザーに警告してください。
• redirectUri は有効な URL で、https:// または http://localhost で始まる必要があります。
• ユーザーが指定した redirectUri のポートが appPort と異なる場合は、警告してください。一致させる必要がある可能性があります。

Well-known URL の構成ガイダンス

エージェントへの指示： ユーザーは完全な well-known URL ではなく、AM のベース URL（例：https://your-tenant.forgeblocks.com/am）を指定することがよくあります。指定された URL が /.well-known/openid-configuration で終わっていない場合：

1. ユーザーに、使用するレルム（AIC では一般的に alpha または bravo）を尋ねてください。
2. 次の形式で well-known URL を構成してください。 <baseUrl>/oauth2/<realm>/.well-known/openid-configuration
3. 構成する前に、ベース URL の末尾にある / を削除してください。
4. 続行する前に、構成した URL をユーザーに確認してください。

例：

• ユーザーが指定：https://openam-myco.forgeblocks.com/am
• エージェントが質問：「どのレルムを使用しますか？（一般的には alpha または bravo）」
• ユーザーが回答：alpha
• エージェントが構成：https://openam-myco.forgeblocks.com/am/oauth2/alpha/.well-known/openid-configuration
• エージェントが確認：「well-known URL としてこれを使用します。こちらで問題ありませんか？」

---

実装手順

ステップ 1 — 環境変数を設定する

プロジェクトのルートに .env ファイルを作成してください。.env のテンプレートを参照してください。

また、シークレットとビルド成果物がバージョン管理に含まれないように、.gitignore を追加してください。.gitignore のテンプレートを参照してください。

エージェントへの指示： すべての <parameter> プレースホルダーを、上記で収集した値に置き換えてください。

VITE_WELLKNOWN_URL=<wellknownUrl>
VITE_WEB_OAUTH_CLIENT=<clientId>
VITE_SCOPE=<scope>
VITE_PORT=<appPort>
VITE_JOURNEY_LOGIN=<journeyLogin>
VITE_JOURNEY_REGISTER=<journeyRegister>
VITE_REDIRECT_URI=<redirectUri>
VITE_DEBUGGER_OFF=true

---

ステップ 2 — 設定定数を作成する

SDK の設定を一元管理するため、constants.jsを作成します。constants.js テンプレートを参照してください。

SDK の設定に必要なのはwellknown URL のみです。Journey クライアントは、well-known ドキュメントからbaseUrl、authenticate、sessionsの各エンドポイントを自動的に導出します。

export const WELLKNOWN_URL = import.meta.env.VITE_WELLKNOWN_URL;
export const WEB_OAUTH_CLIENT = import.meta.env.VITE_WEB_OAUTH_CLIENT;
export const SCOPE = import.meta.env.VITE_SCOPE;
export const REDIRECT_URI = import.meta.env.VITE_REDIRECT_URI || `${window.location.origin}/callback.html`;

export const CONFIG = {
  clientId: WEB_OAUTH_CLIENT,
  redirectUri: REDIRECT_URI,
  scope: SCOPE,
  serverConfig: {
    wellknown: WELLKNOWN_URL,
  },
};

注: VITE_REDIRECT_URIを使用すると、環境変数でリダイレクト URI を設定できます。 省略した場合、デフォルトは${window.location.origin}/callback.htmlです。これは重要です。 ローカル開発ではhttp://を使用し、本番環境ではhttps://を使用する場合があり、リダイレクト URI は PingAM / AIC に登録したものと完全に一致している必要があるためです。

すべての設定オプションについては、SDK パッケージリファレンスの@forgerock/journey-clientのセクションを参照してください。

---

ステップ 3 — OIDC コンテキストプロバイダーを作成する

アプリケーション全体の認証状態を管理するため、oidc.context.jsを作成します。oidc.context.js テンプレートを参照してください。

OIDC コンテキストは、以下を行います。

• アプリのマウント時に OIDC クライアントを初期化する
• 既存のトークンを確認する（セッションの永続化）
• isAuthenticated、oidcClient、ユーザー情報をすべてのコンポーネントに提供する
• トークンを失効させて状態をクリアし、ログアウトを処理する

import { createContext } from 'react';
import { oidc } from '@forgerock/oidc-client';

export const OidcContext = createContext();

export function useInitOidcState(config) {
  // Initialize OIDC client and check for existing session
  // Returns [state, methods] for context consumption
}

API ドキュメントについては、SDK パッケージリファレンスの@forgerock/oidc-clientのセクションと、OIDC 一元管理リファレンス全文を参照してください。

---

ステップ 4 — Journey フックを作成する

Journey 認証フローを管理する中心的なカスタムフックとして、journey.hook.jsを作成します。journey.hook.js テンプレートを参照してください。

主な役割：

• 共有のCONFIGを使用して Journey クライアントを初期化する
• 新しい Journey を開始する（またはリダイレクト後に再開する）
• ステップの送信を処理し、次のノードに進む
• LoginSuccess時に、OIDC クライアントを介してセッションを OAuth トークンと交換する
• LoginFailure時にエラーメッセージを取得し、Journey を再開する
• 描画する現在のステップと、フォーム送信用のメソッドを返す

import { journey, callbackType } from '@forgerock/journey-client';

export default function useJourney({ formMetadata, resumeUrl }) {
  // Returns [state, methods]
  // state: { formFailureMessage, renderStep, submittingForm, user }
  // methods: { setSubmissionStep, setSubmittingForm, redirect }
}

クライアント API の詳細については、SDK パッケージリファレンスの@forgerock/journey-clientのセクションを参照してください。

---

ステップ 5 — Journey フォームコンポーネントを作成する

現在の Journey ステップのコールバックを描画するメインのフォームコンポーネントとして、form.jsxを作成します。form.jsx テンプレートを参照してください。

フォームは、以下を行います。

• useJourneyを使用して、現在のステップと送信メソッドを取得する
• ステップ内の各コールバックを対応する React コンポーネントに割り当てる
• 送信ステップを設定してフォーム送信を処理する
• LoginSuccess時に画面遷移する

import { callbackType } from '@forgerock/journey-client';

export default function Form({ action, followUp, topMessage }) {
  // Maps callbacks to components and handles form lifecycle
}

サポート対象のコールバック実装の全一覧については、このスキルのassets/ディレクトリにあるコールバックのアセットを参照してください。

---

ステップ 6 — コールバックコンポーネントを作成する

各コールバックタイプに対応する React コンポーネントを個別に作成します。コールバックコンポーネントのテンプレートを参照してください。

@forgerock/journey-client がサポートするすべてのコールバックタイプ：

コールバックタイプ	コンポーネント	説明
NameCallback	Text	ユーザー名のテキスト入力
ValidatedCreateUsernameCallback	Text	ポリシー適用によるユーザー名の検証付き入力
StringAttributeInputCallback	Text	汎用の文字列属性（メールアドレス、名前など）
TextInputCallback	TextInput	汎用のテキスト入力フィールド
PasswordCallback	Password	表示切り替え機能付きのパスワード入力
ValidatedCreatePasswordCallback	Password	ポリシー適用によるパスワードの検証付き入力
BooleanAttributeInputCallback	Boolean	ブール属性のチェックボックス切り替え
NumberAttributeInputCallback	NumberInput	数値属性の数値入力
ChoiceCallback	Choice	単一選択のドロップダウン
ConfirmationCallback	Confirmation	アクションの選択肢（送信／キャンセル）
SelectIdPCallback	SelectIdP	ソーシャル／外部 ID プロバイダーの選択
KbaCreateCallback	Kba	セキュリティ質問と回答
TermsAndConditionsCallback	TermsConditions	規約への同意チェックボックス
TextOutputCallback	TextOutput	サーバーのメッセージ（情報、警告、エラー）の表示
SuspendedTextOutputCallback	SuspendedTextOutput	一時停止されたジャーニーのメッセージ（マジックリンク／メール認証）
PollingWaitCallback	PollingWait	自動で次に進む待機ステップ（ユーザー操作なし）
RedirectCallback	Redirect	外部認証（ソーシャルログイン、SAML）のためのブラウザーリダイレクト
DeviceProfileCallback	DeviceProfile	デバイスのメタデータを自動収集して送信
HiddenValueCallback	HiddenValue	画面には表示されず、クライアントとサーバー間で内部状態を受け渡す
MetadataCallback	Metadata	画面には表示されず、サーバーのメタデータをクライアントに渡す
ReCaptchaCallback	ReCaptcha	Google reCAPTCHA v2 ウィジェット
ReCaptchaEnterpriseCallback	ReCaptchaEnterprise	Google reCAPTCHA Enterprise ウィジェット
PingOneProtectInitializeCallback	ProtectInitialize	PingOne Protect の脅威シグナル収集を初期化
PingOneProtectEvaluationCallback	ProtectEvaluation	PingOne Protect の脅威シグナルを収集して送信
WebAuthn (FIDO2)	WebAuthnComponent	FIDO2／パスキーの登録と認証

各コンポーネントは次のパターンに従います：

1. コールバックから表示値を取得します（例：callback.getPrompt()）
2. 適切なフォーム要素を描画します
3. ユーザー入力をコールバックに設定します（例：callback.setInputValue(value)）

注： 自動で次に進むコールバック（PollingWaitCallback、DeviceProfileCallback、RedirectCallback、ReCaptchaCallback、ReCaptchaEnterpriseCallback、PingOneProtectInitializeCallback、PingOneProtectEvaluationCallback）では、ユーザー操作は必要ありません。処理の完了後、ステップが自動的に送信されます。

---

ステップ 7 — ログインビューと登録ビューを作成する

login.jsx ビューと register.jsx ビューを作成します。login.jsx のテンプレートと register.jsx のテンプレートを参照してください。

// login.jsx — Renders the Form component with the login journey
export default function Login() {
  return <Form action={{ type: 'login' }} />;
}

// register.jsx — Renders the Form component with the registration journey
export default function Register() {
  return <Form action={{ type: 'register' }} />;
}

---

ステップ 8 — ログアウトビューを作成する

logout.jsx を作成します。logout.jsx のテンプレートを参照してください。

ログアウトでは OIDC コンテキストを使用してトークンを失効させ、セッションをクリアします：

import { useContext, useEffect } from 'react';
import { OidcContext } from '../context/oidc.context';

export default function Logout() {
  const [, { setAuthentication }] = useContext(OidcContext);
  useEffect(() => { setAuthentication(false); }, []);
  return <p>Logging out...</p>;
}

---

ステップ 9 — 保護されたルートとルーターを作成する

ProtectedRoute コンポーネントとアプリのルーターを作成します。route.jsx のテンプレートと router.jsx のテンプレートを参照してください。

// Protected route — redirects to /login if not authenticated
export function ProtectedRoute({ children }) {
  const [{ isAuthenticated }] = useContext(OidcContext);
  return isAuthenticated ? children : <Navigate to="/login" />;
}

---

ステップ 10 — アプリケーションのエントリーポイントを作成する

コンテキストプロバイダーを使用してアプリを起動するため、index.jsx を作成します。index.jsx のテンプレートを参照してください。

import { OidcContext, useInitOidcState } from './context/oidc.context';
import { CONFIG } from './constants';

function App() {
  const oidcState = useInitOidcState(CONFIG);
  return (
    <OidcContext.Provider value={oidcState}>
      <Router />
    </OidcContext.Provider>
  );
}

---

ステップ 11 — OAuth コールバックページの作成

OAuth リダイレクト応答を処理するため、public/ ディレクトリに callback.html を作成します。callback.html テンプレートを参照してください。

この静的な HTML ページは、OAuth リダイレクトから code と state のパラメーターを取得し、SPA に渡します。

---

ステップ 12～14 — サンプルアプリのみ（プロフィール、ナビゲーション、ルーター）

エージェントへの指示： ユーザーが サンプルアプリケーション モードを選択した場合、またはプロフィールページ、ナビゲーションバー、あるいはルーター全体の配線を明示的にリクエストした場合にのみ、これらのステップを実行してください。

references/sample-app-guide.mdの詳細な手順に従ってください。

• ステップ 12 — oidcClient.user.info()、ユーザー情報クレームの表、編集モーダルのパターンを使用して profile.jsx を作成します
• ステップ 13 — Navbar コンポーネント、CSS スタイルシート、テーマを適用した Home ビューを作成します
• ステップ 14 — 保護されたルートと公開ルートをすべて含めて router.jsx を接続します

---

スキャフォールディングスクリプト

すばやくセットアップするには、スキャフォールディングスクリプトを使用して、すべてのテンプレートファイルをプロジェクトにコピーします。

chmod +x scripts/scaffold_auth.sh
./scripts/scaffold_auth.sh \
    --project-dir ./my-react-app \
    --journey Login

詳細については、scaffold_auth.shを参照してください。

---

よくある間違い

間違い	修正方法
CORS が設定されていない	PingAM / AIC テナントで、アプリのオリジン、メソッド、ヘッダーが許可されていることを確認します
openid スコープがない	OIDC トークン交換に必要なため、必ず openid を含めます
Well-Known URL が間違っている	/.well-known/openid-configuration で終わり、正しいレルムを含める必要があります。ユーザーがベース AM URL だけを提示することがよくあります。その場合はレルムを尋ね、完全な URL を組み立てます。
Well-Known URL ではなく、ベース AM URL を使用している	ユーザーが https://tenant.forgeblocks.com/am を提示した場合は、どのレルム（alpha／bravo）かを尋ね、<baseUrl>/oauth2/<realm>/.well-known/openid-configuration を組み立てます
未処理のコールバックタイプ	Journey で使用するすべてのコールバックタイプについて、mapCallbacksToComponents 関数にケースを追加します
callback.setInputValue() を呼び出していない	ステップを送信する前に、必ずコールバック値を設定します。SDK は設定した値を送信します
リダイレクト URI の不一致	設定の redirectUri は、PingAM / AIC に登録したものと完全に一致する必要があります。プロトコル（http と https）とポート番号も一致させます
リダイレクト URI のポートとアプリのポートが一致しない	ユーザーが redirectUri にポート 8443、appPort に 8444（またはその逆）を指定した場合は、OAuth フローを動作させるには両者を一致させる必要があることを伝えます
HTTP と HTTPS の混在	SDK では本番環境で HTTPS が必要です。ローカル開発では、AIC の OAuth クライアントで http://localhost のリダイレクト URI が設定されていれば、http://localhost を使用できます
LoginSuccess より前にトークン交換を実行している	Journey が LoginSuccess ステップを返した後にのみ、oidcClient.authorize.background() を呼び出します
LoginFailure を処理していない	client.next() の後に必ず LoginFailure を確認します。Journey を再開してエラーを表示します
コールバックを設定せずに client.next() を呼び出している	次のステップに進む前に、必ずコールバック値を設定します
constants.js で oidc をインポートしている	constants ファイルは設定のみをエクスポートします。@forgerock/oidc-client を直接インポートしたり使用したりはしません。OIDC クライアントは oidc.context.js で初期化されます。
サンプルアプリ用の styles.css を生成していない	サンプルアプリでは、フォームフィールド、ボタン、レイアウト、モーダル用のスタイルシートが必要です。必ず client/styles.css を作成し、index.jsx でインポートします。
public/ の callback.html を忘れている	OAuth コールバックページは React ルートではなく、public/ ディレクトリ内の静的 HTML ファイルである必要があります。このファイルがないと、OAuth リダイレクトは何も表示されないページで失敗します。

---

リファレンスドキュメント

• SDK パッケージリファレンス — @forgerock/journey-client、@forgerock/oidc-client、オプションのアドオンのパッケージ選択ガイド
• OIDC 集約リファレンス — @forgerock/oidc-client の API 全般：認可、トークン交換、ユーザー情報、ログアウト、ストレージ
• コールバックの実装 — assets/ 内のテンプレートファイルを参照してください（例：text.jsx.template、password.jsx.template、boolean.jsx.template、webauthn.jsx.template）

---

関連スキル

• ping-orchestration-javascript-sdk — JavaScript の統合スキル（Journey／DaVinci／OIDC に振り分け、Journey フローではここに処理を委任します）
• ping-orchestration-android-sdk — Android（Kotlin／Jetpack Compose）版
• ping-orchestration-ios-sdk — iOS（Swift／SwiftUI）版