アプリケーションにWebプロパティパネルを統合

インテグレーション (統合)

dRofus Web は、ホストアプリケーションのアプリケーションスペース内に dRofus のデータパネルを表示することができるエンベッディングによる統合を提供します。
dRofus 統合アプリはブラウザコンテキストで実行され、HTMLiframe を通じて埋め込まれるか、
アプリ内のブラウザウィジェット (例：Android の WebView、C#/WPF の BrowserControl) でで実行されます。

アプリに関する備考

統合されたdRofusは、起動パフォーマンスを向上させるためにブラウザキャッシュを使用し、アプリケーションアセット (html、css、javascript、画像などの静的ファイル)は初回のみ (または変更された場合) 読み込まれ、それ以降の起動はブラウザキャッシュから提供されます。
アプリでこれを利用するには、ブラウザ・ウィジェットのキャッシュが、アプリケーションが終了しても破棄されないことを確認してください。
統合されたdRofusは、新しいブラウザタブ/ウィンドウを開く場合があります
(ファイルのダウンロード時、または同じコンテキストでdRofusウェブアプリ全体を開く場合など)。
ブラウザウィジェットのデフォルトの実装は、このような外部ナビゲーション(target="_blank")を無視します。
ホストは、例えばWPF WebViewの NewWindowRequested イベントのように、このようなイベントを実装して処理する必要があります。

認証とトークン (アンカー｜ログイン_スタートアップ)

dRofus のアプリケーションは、Web、デスクトップ共に、ユーザーのログインが必要です。
ログイン時に、ユーザー名、パスワード、プロジェクトの選択が必要です。
プロジェクトの選択は、サーバー、データベース、プロジェクト (データベースに複数設定されている場合) を選択します。

dRofus 統合アプリで必要な認証は OIDC 標準に準拠しています。ログインの手順は以下の通りです：

エンベッダーは有効なトークンを持っていなければなりません。
dRofusの統合アプリケーションは、ホストからトークンを取得する必要がある場合、それを実行します。
dRofus 統合アプリケーションがトークンを検証し、ホストに通知します。

備考：トークンは単なる文字列です。JWTトークンを使用しますが、解析する必要はありません。

トークンの取得

各データベースサーバーは、対応するOIDCサーバーインスタンスを持っています。トークンを取得するために、
エンベッダーは選択した OIDC server' (OIDCサーバー) の認証エンドポイントに接続する必要があります。
当社の統合ソリューションは、PKCE タイプの OIDC 暗黙的またはコードグラントに対応しています。コードグラント(code grant)の使用をお勧めします。

登録

エンベッダーは事前にアプリケーションを弊社に登録してください。この登録は現在手動です。
その結果、エンベッダーは、トークン生成時に (クライアントの) アプリケーションを識別するための認証情報を持つことになります。
このような認証情報 (credentials)には、client_id、client_secret（該当する場合）、および1つまたは複数のredirect_uriが含まれます。

1. Implicit grant – Deprecated

備考：OAuth 2.1標準に基づき、暗黙的な付与は推奨されません：コードグラント (code grant)を使用してください。

このようなOIDCリクエストには以下のパラメータが必要です：

response_type: token
client_id: your_client_id (以前に登録された)
scope: dr-std embed
redirect_uri: your_redirect_uri (以前に登録された)

オプショナル：

db およびpr: データベース名とプロジェクト番号 (例："01", "02 "など)。省略された場合、ユーザーは認証後にプロジェクトを選択できるようになります。

リダイレクトURI (“callback URI (コールバックURI) ”とも呼ばれます) は、事前に弊社に登録しておく必要があります。
アプリケーション用に複数のリダイレクトURIを登録することもできます。トークン取得リクエストは、リダイレクトURIを含まなければなりません。
リダイレクトURIは、以前に登録されたURIのいずれかと一致しなければなりません。

2. PKCEによるコード・グラント (Code grant )

このようなOIDCリクエストには以下のパラメータが必要です：

response_type: code
client_id: your_client_id (前に登録された)
client_secret: your_client_secret (事前に登録されたクリアテキスト)
scope: dr-std embed
redirect_uri: your redirect URI (前に登録された)

備考：コードグラントをWebアプリケーションで使用する場合、redirect_uri はエンベッダーが管理するWebアプリケーションを指す有効なURLで、
なければなりませんので、暗黙的グラントの場合と同様に登録する必要があります。リダイレクトURIはアプリではあまり重要ではなく、
どんなURIでも使うことができ、実際のウェブサイトを指す必要はありません。ただし、事前に登録したURIと一致する必要があります。

code_challenge: PKCEのコードチャレンジを送信
code_challenge_method: PKCE のチャレンジメソッドを送信します、 S256 (SHA256を示す)を設定する必要があります。

オプションのパラメータ：

db および pr：データベース名とプロジェクト番号 (例："01", "02 "など)。省略された場合、ユーザーは認証後にプロジェクトを選択できるようになります。

ログイン後

ログイン後、ブラウザのセッションは要求されたリダイレクト URI にリダイレクトされます。デフォルトの応答タイプでは、url フラグメントに result が追加されます。
あるいは、フォーム投稿の結果を選択することもできます。トークンはacces_token 結果パラメータにエンコードされます。
ログインに失敗した場合 (エラーまたはユーザーキャンセル)、トークンが含まれていません。

備考：ブラウザ環境ではブラウザ環境ではCORS制限が適用されます。
リダイレクトURIのオリジンを登録しますが、リダイレクトURIとイニシエータのオリジンが異なる場合はお知らせください。

Passing the token

備考：このワークフローは、公開されたトークンがある種の攻撃に対して脆弱であるため、現在は廃止されています。

1. メッセージング

エンベッダーは、以下のパスとハッシュで、次のアプリケーションサーバーを呼び出すことにより、統合されたDrofusにトークンを渡す必要があります。

/embedded/signin#access_token=<insert token here>

トークンが認証されると、エンベッダーのウィンドウ・オブジェクトにメッセージが送られます。メッセージのペイロードには、DrofusEmbedded という、
オブジェクトとsuccessful (成功したフラグ) が含まれます。成功したメッセージは：

{ "DrofusEmbedded": { "success": true } }

2. リダイレクト

エンベッダーは、以下のパスとハッシュで、次のアプリケーションサーバーを呼び出すことにより、統合されたDrofusにトークンを渡す必要があります。

/embedded/signin?response=redirect#access_token=<insert token here>

トークンが認証されると、アプリケーションは /embedded/signin-ready にリダイレクトするので、エンベッダーはURL変更イベントをリッスンする必要があります。
クエリ文字列は成功したかどうかを示し、場合によってはエラーメッセージも含まれる。成功したURLは：

/embedded/signin-ready?success=true

サーバー設定

データベース	アプリケーション・サーバー	oidc サーバー
db2.nosyko.no	https://app-db2.drofus.com	https://ids-db2.drofus.com

スタートアップ＆コミュニケーション

dRofus 統合アプリを起動するには、ホストの iframe またはブラウザウィジェットに URL を読み込む必要があります。
URLは /embeddedのパスを対応するアプリケーション・サーバー.

dRofus 統合アプリは、複数の場面でホストと通信します：アクセストークンを要求したり、起動プロセス、ユーザーナビゲーション、
あるいは最終的な失敗を通知したりします。ホストはトークンリクエストを受信すると、応答しなければなりません。それ以外のイベントは情報のみです。

2種類の通信チャネルが有効になっています：

ブラウザ内メッセージング。これは、iframeを使用するブラウザベースのウェブホストに推奨されます。
Httpベースのコールバック。これは、ネイティブアプリケーションのような非ブラウザホストに推奨されます。

デフォルトでは、ブラウザ内のメッセージングが使用されています。メッセージ・フォーマットの詳細については、通信タイプごとに説明します。

ブラウザ内メッセージング

メッセージングは、異なるwindow (ウィンド)ウオブジェクト間で安全なバックチャネルを提供します。
詳細はこちら：ウィンドウのポストメッセージ() - Web API | MDN (mozilla.org).

この場合、ホストのウィンドウとdRofus統合アプリのiframeの間です。注意すべき点：

ウィンドウ・オブジェクトにイベント・リスナーを追加することで、メッセージを有効にすることができます。
常にメッセージのオリジン・プロパティをチェックしてください。他の人からのメッセージも受け取る可能性があるかもしれません。
返信が必要な場合は、iframe.contentWindowにメッセージを投稿してください。
dRofusからの受信メッセージはすべて{ DrofusEmbedded: { ... } } オブジェクトの中にラップされます。

トークンの取得

dRofus 統合アプリは、requestAccessToken ペイロードとランダムな文字列識別子を含むメッセージを送信することで、
トークンを要求します。メッセージは以下のようになります：

{ DrofusEmbedded: { requestAccessToken: "random identifier" } }

ホストは、文字列識別子とアクセストークンの値を以下の形式でdRofus統合アプリに返信（実際には別のメッセージを投稿）する必要があります：

{ id: "random identifier", accessToken: "..." }

備考： 起動前にアクセストークンを準備してください。トークンのリクエストは5秒後にタイムアウトします。

次のスニペットは、そのような要求をどのように処理するかの例を示しています。

CODE

const iframe = document.getElementById('drofus');
const drofusAccessToken = 'abcd...';
window.addEventListener('message', message => {
    if (message.origin !== drofusAppServer)
        return;

    console.log('Message received from dRofus app', message.data);

    if (message.data.DrofusEmbedded && message.data.DrofusEmbedded.requestAccessToken)
        onTokenRequest(message.data.DrofusEmbedded.requestAccessToken);
});

function onTokenRequest(id) {
    iframe.contentWindow.postMessage({ id, accessToken: drofusAccessToken }, '*')
}

dRofus 統合アプリは、トークンが取得されると通知されたイベントを送信し、無効な場合(期限切れなど)はエラーになります。

Http-コールバック

これは今後の機能です。現在進行中であり、決定次第ドキュメント化する予定です。

Httpリクエストはブラウザ環境から送信されるため、いくつかの制限が適用されます。

CORS

したがって、エンベッダーはレスポンスにCORS関連ヘッダーを含め、リクエストのオリジンを有効にする必要があります。例えば：

Access-Control-Allow-Origin: <origin of dRofus Integrated app or *>

混合コンテンツ

drofus 統合アプリは HTTPS 経由で提供されています。セキュリティ上の理由から、ブラウザは混在した内容（安全なサイトが安全でないリソースを要求する場合）の発信Httpコールの発信を拒否します。実際には、ブラウザは HTTPS プロトコルを介したコールバックのみを許可します。
ブラウザによっては、例えば "http://localhost:8080"のように、HTTP経由のループバックを安全なものとみなすものもあります。
詳細はこちら：n: 混合コンテンツ - Webセキュリティ｜MDN (mozilla.org)

デモ

OIDCはよく知られた規格であり、ほとんどのプラットフォームで利用可能な多くの公共および無料のライブラリがあります。
お客様の便宜を図るため、デモ・アプリケーションを作成しました。

1. HTML iframe、インプリシットグラント、メッセージング

https://code.drofus.com/projects/BALAZS/repos/embed-demo

oidc-client-js ライブラリ：
GitHub - IdentityModel/oidc-client-js： OpenID Connect (OIDC) と OAuth2 プロトコルをブラウザベースの JavaScript アプリケーションでサポートが使用されているが、
サポートライブラリなしで実装されている場合もあります。

2. アプリ、コードグラント、リダイレクト

dRofus COMMON / Api. サンプルを見る - dRofus Bitbucket

Api を検索

これは今後の機能です。現在進行中ですが、決定次第ドキュメント化されます。

dRofus 統合アプリは、バック・チャンネルでさまざまなエンティティの検索を提供します。
一旦終了すると、フロント・チャンネル (すなわちナビゲーション・ベース) の検索は廃止され、idによるエンティティの表示のみが残ります。

検索する属性

部屋

属性ID	説明

dRofusのコンテンツを表示する

dRofus 統合アプリケーションのコンテンツは、ホストまたはユーザーによる操作 (リンクのクリックなど) の結果として表示されます。
ホストはアプリケーションのURLを通じてコンテンツを制御します。

備考：dRofusの統合アプリケーションは、ナビゲーションにSingle Page Application-techniqueを使用しています。
つまり、アプリケーションは起動時にHTMLドキュメントとアセットをロードし、ユーザーとのインタラクション時にのみサーバーからデータをロードします
(完全にレンダリングされたHTMLドキュメントがロードされ、データがブレンドされる従来のアプリケーションとは対照的です)。
これは、しばしばクライアント・サイド・ナビゲーションと呼ばれています。これはホストに影響を与えません。

コンテンツは、/embedded パスと、それに続く1つのフロントエンドURL (URLフラグメント/ハッシュとして) で構成されています。

待受画面

フロントエンドのURL- 部分のないコンテンツや、# (empty hash/空のハッシュ) の後に何もないコンテンツは、"idle (待受け)" 画面 -- dRofusのロゴ -- になります。
これは何も表示しない場合に有効です。起動後に/embedded と表示されます。

許可されたフロントエンドのURL

#/rooms/search?value={searchValue}
#/rooms/search/{attributeId}?value={searchValue}
部屋を検索します。検索結果が1件の場合、詳細パネルを表示します。複数の場合、セレクタが表示されます。
パラメータ
- searchValue
  : 検索対象の定義する。
- attributeId
  : 検索するフィールドを定義するオプションのパラメータ。
#/rooms/room/{roomId}
部屋の詳細パネルを表示する。
パラメータ
- roomId
  : Drofus 部屋の識別子（整数値）
#/articles/search?value={searchValue}
#/articles/search/{attributeId}?value={searchValue}
アイテムを検索します。検索結果が1つの場合、詳細パネルを表示します。複数の場合はセレクタが表示されます。
パラメータ
- searchValue
  : 検索対象の定義する。
- attributeId
  : 検索するフィールドを定義するオプションのパラメータ。
#/articles/article/{articleId}
アイテムの詳細パネルを表示する。
パラメータ
- articleId
  : Drofus 品の識別子 (整数)
#/occurrences/search?value={searchValue}
#/occurrences/search/{attributeId}?value={searchValue}
オカレンスを検索する。結果が1つの場合、詳細パネルが表示されます。複数の場合はセレクタが表示されます。
パラメータ
- searchValue
  : 検索対象を定義する。
- attributeId
  : 検索するフィールドを定義するオプションのパラメータ。
#/occurrences/occurrence/{occurrenceId}
オカレンス詳細パネルを表示する。
パラメータ
- occurrenceId
  : Drofus オカレンス識別子 (整数)

ユーザー・ナビゲーション

dRofus Web および統合アプリでは、多くの場合、エンティティ間の関係 (アイテム-オカレンス、部屋-オカレンスなど) のリンクが表示されます。
dRofus 統合アプリは、ユーザがこれらのリンクをたどることができるようにしており、これをユーザナビゲーションと呼んでいます。
ユーザーナビゲーションが発生した場合、dRofus 統合アプリはエンベッダーに通知します。

通知は、エンベッダの親ウィンドウオブジェクトに送られるメッセージイベントです。
メッセージのペイロードには、送信先の名前とパラメータ (エンティティIDなど) が含まれます。

備考：

この機能は試験的なものであり、実装の詳細は急遽変更される可能性があります。実際のメッセージフォーマットは、確定次第ドキュメントに追加します。
現在、エンベッダによるユーザーナビゲーションのキャンセルはできません。
現在の実装では、メッセージベースのワークフローしかサポートしていません。これはHTMLのiframe環境には適していますが、アプリには適していないかもしれません。アプリの提案として、エンベッダがHTTPサーバをホストし、そこにdRofus統合アプリがデータをポストする方法があります。
何かご提案がありましたら、ご連絡ください。