ping-orchestration-javascript-sdk

Ping JavaScript SDK

Ping Orchestration JavaScript SDK（@forgerock/journey-client、@forgerock/davinci-client、@forgerock/oidc-client）を使ってウェブアプリを構築する際の最初の窓口です。次の3つの認証フローに対応します。

• Journey — PingAM または PingOne AIC に対するコールバックベースの認証 → ping-orchestration-reactjs-journey-sdk に委譲します
• DaVinci — PingOne DaVinci に対するコレクターベースの認証 → ping-orchestration-reactjs-davinci-sdk に委譲します
• OIDC centralized login — OAuth2 認可コードフロー（ブラウザーリダイレクト）→ この中で処理します

フローの種類の判定、フレームワークの検出、共通設定の収集を行い、その後に処理を引き継ぐかコードを生成する、3段階のウィザード（W1 → W2 → W3）を実行します。

Framework Registry

この表は、フレームワークのルーティングに関する唯一の信頼できる情報源です。判定ツリーは Status を参照します。フレームワークを追加するには、ステータスを placeholder から active に変更し、委譲先のスキル名を追加し、OIDC テンプレートディレクトリを入力して、「Build Tool Configuration」サブセクションにビルドツール固有のガイダンスを追加します。

フレームワーク	Journey の委譲先	DaVinci の委譲先	OIDC テンプレート	ステータス
React	ping-orchestration-reactjs-journey-sdk	ping-orchestration-reactjs-davinci-sdk	assets/react/	active
Angular	—	—	assets/angular/	placeholder
Vue	—	—	assets/vue/	placeholder
Vanilla JS	—	—	assets/vanilla/	placeholder

Wizard

create-sample 引数なしでスキルが呼び出されるたびに、次の3つのステップを実行します。

W1 — フローの種類

次のように質問します。

どのフローを構築しますか？

1. Journey — PingAM または PingOne AIC に対するコールバックベースの認証
2. DaVinci — PingOne DaVinci に対するコレクターベースの認証
3. OIDC centralized login — OAuth2/OIDC 認可コードフロー（ブラウザーリダイレクト、カスタム UI は不要）

W1b — フレームワークの検出

設定を収集する前に、ユーザーのフレームワークを検出するか、質問します。

package.json が存在する場合は、次を実行します。

grep -E '"(react|vue|@angular/core|vite)"' package.json

• react が見つかった場合 → React を検出 → W2 に進みます。
• vue または @angular/core が見つかった場合 → プレースホルダーであることを伝え、次の選択肢を提示します。

  「専用の ping-orchestration-vue-sdk / ping-orchestration-angular-sdk スキルを準備中です。次のことができます。

  1. フレームワークに依存しない SDK の接続方法を生成する — クライアントの初期化、トークン交換、ルートガードの疑似コードを生成します。お使いのフレームワークのパターンに合わせて調整できます。
  2. 参考実装として React スキルにルーティングする（ping-orchestration-reactjs-journey-sdk / ping-orchestration-reactjs-davinci-sdk）。お使いのフレームワークに移植できます。

  どちらを希望しますか？」

  • ユーザーが選択肢1を選んだ場合 → W2 に進み、その後、以下の 汎用（プレースホルダーフレームワーク）パスを使用します。
  • ユーザーが選択肢2を選んだ場合 → W2 に進み、React スキルに委譲します。
• react-native が見つかった場合（個別に確認）→ ping-orchestration-react-native-sdk を準備中であることを伝えます。暫定的な代替手段はありません。
• 何も見つからない場合、または package.json がない場合 → 「どの JavaScript フレームワークを使用していますか？」と質問します。Framework Registry にある有効なフレームワークを一覧表示します。ユーザーがプレースホルダーのフレームワークを指定した場合は、上記と同じ2つの選択肢を提示します。

W2 — 共通設定

以下のパラメーターを収集します。ユーザーがメッセージ内ですでに指定しているものは省略します。

パラメーター	必要なフロー	備考
wellknown	すべてのフロー	.well-known/openid-configuration で終わる完全な OIDC ディスカバリー URL
clientId	すべてのフロー	PingOne/AIC に登録された OAuth クライアント ID
redirectUri	すべてのフロー	登録値と完全に一致する必要があります。末尾に /callback パスを含めてください
scope	すべてのフロー	スペース区切り。openid を含める必要があります
appName	すべてのフロー	プロジェクト／ディレクトリ名に使用します
journeyName	Journey のみ	認証ツリー名（例：Login）
acrValues	DaVinci/OIDC のみ	任意の ACR 値文字列

W3 に進む前の検証：

• wellknown は .well-known/openid-configuration で終わる必要があります
• scope には openid を含める必要があります。含まれていない場合は追加し、そのことをユーザーに伝えてください
• redirectUri は http:// または https:// で始まる絶対 URL である必要があります

W3 — 確認と引き継ぎ

概要テーブルを表示します。

パラメーター	値
フロー	<journey | davinci | oidc-centralized>
フレームワーク	<React>
Well-known URL	<wellknown>
クライアント ID	<clientId>
リダイレクト URI	<redirectUri>
スコープ	<scope>
アプリ名	<appName>
Journey 名 (Journey のみ)	<journeyName>
ACR 値 (DaVinci/OIDC、指定された場合)	<acrValues>

次のように尋ねます：「内容に間違いはありませんか？続行しますか？」

確認後：

• Journey（有効なフレームワーク） → Skill ツールを介して、Framework Registry から Journey デリゲートを呼び出します。収集した設定を呼び出しコンテキストに渡してください。そのスキルの内容をインラインで含めないでください。注：Journey デリゲートは独自の環境変数名（VITE_WELLKNOWN_URL、VITE_WEB_OAUTH_CLIENT など）を使用します。デリゲート側で処理するため、W2 の論理値を渡してください。
• DaVinci（有効なフレームワーク） → Skill ツールを介して、Framework Registry から DaVinci デリゲートを呼び出します。収集した設定を渡してください。そのスキルの内容をインラインで含めないでください。注：DaVinci デリゲートは独自の環境変数名（VITE_CLIENT_ID、VITE_DISCOVERY_ENDPOINT など）を使用するため、W2 の論理値を渡してください。
• OIDC centralized（有効なフレームワーク） → assets/oidc-centralized-reference.md を読み、以下の OIDC Centralized Login セクションに進みます。フレームワークの OIDC Templates ディレクトリにあるテンプレートを使用してください。
• すべてのフロー（placeholder framework、汎用パス） → 以下の Generic (Placeholder Framework) Path セクションに進みます。

Generic (Placeholder Framework) Path

ユーザーのフレームワークが Framework Registry で placeholder となっており、W1b でフレームワークに依存しない SDK の配線を選択した場合に、このパスを使用します。SDK パッケージは純粋な JavaScript で、特定のフレームワークに依存しません。このパスでは、フレームワーク固有のコンポーネント描画に依存しない統合配線を提供します。

生成するもの

フローの種類ごとに、ユーザーが自身のフレームワークに合わせて調整できる単一の統合モジュールを作成します。

Journey：

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

// 1. Initialise OIDC client (for token management after Journey completes)
const oidcClient = await oidc({ config: {
  serverConfig: { wellknown: '<wellknown>' },
  clientId: '<clientId>',
  redirectUri: '<redirectUri>',
  scope: '<scope>',
} });

// 2. Start Journey
const client = await journey({
  serverConfig: { wellknown: '<wellknown>' },
  journeyName: '<journeyName>',
});

let step = await client.start();

// 3. Loop: render callbacks, collect input, submit
while (step.type === 'Step') {
  for (const cb of step.callbacks) {
    // Inspect cb.type (callbackType.NameCallback, callbackType.PasswordCallback, etc.)
    // Collect user input and call cb.setInput(value) or equivalent setter
  }
  step = await client.next(step);
}

// 4. Handle outcome
if (step.type === 'SuccessStep') {
  // Journey complete — tokens available via oidcClient.token.get()
} else {
  // step.type === 'FailureStep' — display error
}

DaVinci：

import { davinci } from '@forgerock/davinci-client';

const client = await davinci({
  serverConfig: { wellknown: '<wellknown>' },
  clientId: '<clientId>',
  redirectUri: '<redirectUri>',
  scope: '<scope>',
});

let node = await client.start();

// Loop: render collectors, collect input, submit
while (node.status === 'continue') {
  const collectors = node.client.collectors;
  for (const collector of collectors) {
    // Inspect collector.type (TextCollector, PasswordCollector, SubmitCollector, etc.)
    // Set value: collector.value = userInput;
  }
  node = await client.next();
}

if (node.status === 'success') {
  // Auth complete — session established
} else {
  // node.status === 'error' — display node.error
}

OIDC centralized：

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

const CONFIG = {
  serverConfig: { wellknown: '<wellknown>' },
  clientId: '<clientId>',
  redirectUri: '<redirectUri>',
  scope: '<scope>',
};

const client = await oidc({ config: CONFIG });

// Login: redirect to authorization endpoint
const url = await client.authorize.url();
window.location.href = url;

// Callback page: exchange code for tokens
const params = new URLSearchParams(window.location.search);
const code = params.get('code');
const state = params.get('state');
if (code && state) {
  await client.token.exchange(code, state);
  window.location.replace('/');
}

// Check auth state
const tokens = await client.token.get();

// Logout
await client.user.logout();

含めるガイダンス

統合モジュールの生成後：

1. フレームワークに関わる部分を説明します（レンダーループ → コンポーネントツリー、認証チェック → ルートガード、コールバックページ → 専用ルート）。
2. 参考実装全体として、React デリゲートスキルを紹介します。
3. アプリの構成を共有してもらえれば、ユーザー固有のフレームワークのパターンにモジュールを組み込む方法を支援できると伝えます。

共通セットアップガイダンス

このセクションは、フローの種類やフレームワークに関係なく適用されます。委譲またはコード生成の前に、このガイダンスを提示してください。

SDK のセットアップ（すべてのフレームワーク）

パッケージの詳細なリファレンス：references/sdk-packages.md

フローに必要なパッケージのみをインストールします。

# Journey
npm install @forgerock/journey-client @forgerock/oidc-client

# DaVinci
npm install @forgerock/davinci-client
# Add @forgerock/oidc-client if you need token management beyond DaVinci's built-in session

# OIDC centralized login
npm install @forgerock/oidc-client

# Optional add-ons (any flow)
npm install @forgerock/protect       # PingOne Protect / behavioral signals
npm install @forgerock/device-client # Device profile, OATH, Push, WebAuthn management

よくある落とし穴（SDK レベル）

• redirectUri の不一致：値は PingOne/AIC に登録されているものと完全に一致している必要があります。末尾のスラッシュ、ポート番号、パスのすべてが重要です。
• openid スコープがない：@forgerock/oidc-client ではスコープに openid が必要です。指定しないとトークン交換に失敗します。
• CORS：well-known エンドポイントでは、サーバーの CORS ポリシーにアプリのオリジンを含める必要があります。プリフライトで失敗する場合は、PingOne/AIC の CORS 設定を確認してください。
• wellknown と serverConfig の違い：新しい SDK（@forgerock/journey-client v2+）では wellknown のみを使用します。従来の serverConfig.baseUrl はサポートされていません。

ビルドツールの設定

検出されたフレームワークに該当するセクションを適用してください。プロジェクトごとに該当するのは 1 つだけです。

**プレースホルダーフレームワーク（Angular、Vue、Vanilla JS）に関する注意：**これらのフレームワークでは、スキルの完全なサポートはまだ有効になっていません。以下のセクションでは、汎用プレースホルダーフレームワークのパスを使用する際に環境を正しく設定できるよう、適切なビルドツールの規約を説明しています。プレースホルダーフレームワーク向けの OIDC テンプレートは生成されないため、パターンを手動で適用してください。

React + Vite

環境変数には VITE_ プレフィックスを使用します（クライアント側に公開するため、Vite で必須です）。

VITE_PING_WELLKNOWN=https://auth.example.com/am/oauth2/alpha/.well-known/openid-configuration
VITE_PING_CLIENT_ID=my-app
VITE_PING_REDIRECT_URI=http://localhost:5173/callback
VITE_PING_SCOPE=openid profile
# Journey only:
VITE_PING_JOURNEY_NAME=Login
# DaVinci/OIDC optional:
VITE_PING_ACR_VALUES=

参照：assets/react/.env.template

Vite 固有の落とし穴：

• VITE_ で始まる変数のみがブラウザーバンドルに公開されます。サーバー専用のシークレットにはプレフィックスを付けないでください。
• インラインの oidc().token.exchange() スクリプトを含む静的な public/callback.html を配置しないでください。@forgerock/oidc-client がサイレントなトークン更新のために authorize.background() を呼び出すと、認可エンドポイントへの非表示の iframe が開き、redirectUri にリダイレクトされます。その URL にある静的スクリプトが 2 つ目の OIDC クライアントを初期化してコードの交換を開始すると、iframe を乗っ取り、iframe のタイムアウトエラーが発生します。代わりに、通常のルートとして React アプリ内でコールバックを処理してください（oidc-callback.jsx.template を参照）。

Angular CLI

環境変数は src/environments/environment.ts に記述します。

export const environment = {
  pingWellknown: 'https://auth.example.com/am/oauth2/alpha/.well-known/openid-configuration',
  pingClientId: 'my-app',
  pingRedirectUri: 'http://localhost:4200/callback',
  pingScope: 'openid profile',
  // Journey only:
  pingJourneyName: 'Login',
};

Angular 固有の注意事項：

• 設定には environment.ts / environment.prod.ts を使用してください。Angular では process.env はブラウザーに公開されません。
• コールバックルートは通常の Angular ルートコンポーネントです。Angular のルーターが処理するため、静的 HTML による回避策は必要ありません。

Vue CLI / Vite

環境変数には、使用するビルドツールに対応するプレフィックスを使用します。

• Vite → VITE_ プレフィックス（上記の React + Vite と同じ）
• Vue CLI（webpack） → VUE_APP_ プレフィックス

VUE_APP_PING_WELLKNOWN=https://auth.example.com/am/oauth2/alpha/.well-known/openid-configuration
VUE_APP_PING_CLIENT_ID=my-app
VUE_APP_PING_REDIRECT_URI=http://localhost:8080/callback
VUE_APP_PING_SCOPE=openid profile

process.env.VUE_APP_*（Vue CLI）または import.meta.env.VITE_*（Vite）でアクセスします。

Vanilla JS / その他

フレームワーク固有の環境変数の規約はありません。プロジェクトに適した方法を使用してください。

• 定数をエクスポートする config.js ファイル
• ビルド時に dotenv で読み込む .env
• ビルド工程のない環境向けのインライン <script> 変数

create-sample コマンド

/ping-orchestration-javascript-sdk create-sample "<description>"

手順：

1. 説明を分析し、フロータイプ（journey／davinci／oidc-centralized）とフレームワークを判断します。
2. フロータイプが曖昧な場合は、確認の質問を1つします。
3. フレームワークが React ではなく、プロジェクトから判別できない場合は、ユーザーに確認します。
4. 説明から推測できない W2 の必須パラメーターが不足している場合は、ユーザーから収集します。
5. Framework Registry でフレームワークが active の場合：
   • Journey → 事前入力済みの設定を使用して、Skill ツール経由で Journey デリゲートを呼び出します。
   • DaVinci → 事前入力済みの設定を使用して、Skill ツール経由で DaVinci デリゲートを呼び出します。
   • OIDC centralized → assets/oidc-centralized-reference.md を読み込み、フレームワークの OIDC Templates ディレクトリにあるテンプレートのプレースホルダーを置換して生成します。
6. フレームワークが placeholder の場合は、Generic（Placeholder Framework）パスを使用します。

テンプレートのプレースホルダー（OIDC centralized のみ）：

プレースホルダー	値
PLACEHOLDER_APP_NAME	appName
PLACEHOLDER_WELLKNOWN	wellknown
PLACEHOLDER_CLIENT_ID	clientId
PLACEHOLDER_REDIRECT_URI	redirectUri
PLACEHOLDER_SCOPE	scope
PLACEHOLDER_ACR_VALUES	acrValues — 指定されていない場合は行を省略します

OIDC Centralized ログイン

インラインで処理され、委譲は行いません。@forgerock/oidc-client を直接使用します。API リファレンス全体は assets/oidc-centralized-reference.md を参照してください。

フロー

1. ユーザーがログインページにアクセスします → client.authorize.url() を呼び出して認可 URL を生成します → ブラウザーをリダイレクトします。
2. ユーザーが PingOne/AIC で認証します → ブラウザーが redirectUri に戻ります。
3. コールバックページが URL から code と state を読み取ります → client.token.exchange(code, state) を呼び出します → トークンが保存されます。
4. アプリが client.token.get() を呼び出してトークンを読み取ります → ユーザーが認証され、保護されたコンテンツが表示されます。
5. バックグラウンド更新：client.token.get({ backgroundRenew: true }) を呼び出し、非表示の iframe 経由でセッションを維持します。
6. ログアウト：client.user.logout() を呼び出します → アクセストークンを失効させ、サーバー上のセッションを終了します。

クライアントの初期化

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

const CONFIG = {
  serverConfig: {
    wellknown: import.meta.env.VITE_PING_WELLKNOWN,
  },
  clientId: import.meta.env.VITE_PING_CLIENT_ID,
  redirectUri: import.meta.env.VITE_PING_REDIRECT_URI,
  scope: import.meta.env.VITE_PING_SCOPE,
  // acrValues: import.meta.env.VITE_PING_ACR_VALUES, // uncomment if needed
};

const client = await oidc({ config: CONFIG });

トークン交換（コールバックページ）

const params = new URLSearchParams(window.location.search);
const code = params.get('code');
const state = params.get('state');

if (code && state) {
  await client.token.exchange(code, state);
  window.location.replace('/');  // redirect to home after successful exchange
}

ルートガードのパターン

ルートガードのロジックはすべてのフレームワークで同じです。コンポーネントのラッパーのみが異なります。

コアロジック（フレームワークに依存しません）：

async function checkAuth(client) {
  const tokens = await client.token.get();
  if (!tokens) {
    const url = await client.authorize.url();
    window.location.href = url;
    return null;
  }
  return tokens;
}

React ラッパー：

import { useEffect, useState } from 'react';

export function ProtectedRoute({ children }) {
  const [isAuthenticated, setIsAuthenticated] = useState(null);

  useEffect(() => {
    client.token.get().then((tokens) => {
      setIsAuthenticated(!!tokens);
    });
  }, []);

  if (isAuthenticated === null) return <div>Loading…</div>;
  if (!isAuthenticated) {
    client.authorize.url().then((url) => { window.location.href = url; });
    return null;
  }
  return children;
}

その他のフレームワークでは、同じ checkAuth ロジックを使用し、フレームワークのガード機構（Angular の CanActivate、Vue の beforeEach ナビゲーションガードなど）に合わせてラッパーを調整してください。

テンプレート

フロータイプが oidc-centralized の場合は、以下のファイルを生成します。Framework Registry の OIDC Templates 列にある、アクティブなフレームワークのサブディレクトリ（React の場合は assets/react/ など）からテンプレートを読み込みます。プレースホルダーを置換し、ユーザーのプロジェクトディレクトリに書き込みます。

React（assets/react/）：

テンプレートファイル	出力パス	目的
assets/react/.env.template	.env	環境変数（Vite の VITE_ プレフィックス）
assets/react/oidc-app.jsx.template	src/App.jsx	OIDC コンテキストと保護されたルートを含むアプリシェル
assets/react/oidc-login.jsx.template	src/pages/Login.jsx	ログインの開始（authorize.url() → リダイレクト）
assets/react/oidc-callback.jsx.template	src/pages/Callback.jsx	コード交換ハンドラー（React コンポーネント経由の token.exchange）
assets/react/oidc-home.jsx.template	src/pages/Home.jsx	サインインの CTA、ユーザー情報、サインアウトを含むホームページ

その他のフレームワーク： OIDC Templates ディレクトリにテンプレートが用意されている場合は、同じパターンに従い、フレームワークの assets/<framework>/ ディレクトリから読み込みます。

よくある落とし穴（OIDC）

• state の不一致：認可 URL を手動で作成しないでください。必ず client.authorize.url() を使用してください。この関数は state と code_verifier（PKCE）を自動的に生成して保存します。保存された state と一致しない state を指定して token.exchange を呼び出すと、state_mismatch がスローされます。
• バックグラウンドでの更新には iframe の許可が必要です：backgroundRenew: true を指定すると、認可エンドポイントを開く非表示の iframe が作成されます。CSP で frame-src がブロックされていると、更新は通知なく失敗します。PingOne/AIC ドメインを frame-src に追加してください。
• PKCE は常に有効です：@forgerock/oidc-client はデフォルトで PKCE を使用し、切り替えオプションは公開していません。OAuth クライアントの登録で PKCE を有効にするか、任意に設定する必要があります。