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

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

アプリの備考

1. 統合されたdRofusは、起動パフォーマンスを向上させるためにブラウザキャッシュを使用し、アプリケーションアセット 統合されたdRofusは、起動パフォーマンスを向上させるためにブラウザキャッシュを使用し、
   アプリケーションアセット (html、css、javascript、画像などの静的ファイル)は初回のみ (または変更された場合) 読み込まれ、それ以降の起動はブラウザキャッシュから提供されます。
   アプリでこれを利用するには、ブラウザ・ウィジェットのキャッシュが、アプリケーションが終了しても破棄されないことを確認してください。

2. 統合されたdRofusは、新しいブラウザタブ/ウィンドウを開く場合があります
   (ファイルのダウンロード時、または同じコンテキストでdRofusウェブアプリ全体を開く場合など)。
   ブラウザウィジェットのデフォルトの実装は、このような外部ナビゲーション(target="_blank") を無視します。
   ホストは、例えばWPF WebViewの NewWindowRequested イベントのように、このようなイベントを実装して処理する必要があります。

...

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

...

• response_type: token

• client_id: your_client_id(以前に登録された)

• scope: dr-std embed

• redirect_uri: your_redirect_uri (以前に登録された)

オプショナル：

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

...

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

Passing the token

Remark: This workflow is now depricated due to exposed token is vulnerable for certain type of attacks

Embedder is responsible for handling the token. If the token is missing, experid or invalid, dRofus integrated web application will send an error message and won't start. Embedder may store token or discard and re-login between startups of Drofus Integrated App.

Embedder should create an integrated Drofus environment and load the corresponding application server's address with the following path and hash, where the hash includes the token from the previous step. After the token is received, Drofus Integrated App is validating the token. When validated, both successful and unsuccesful, dRofus integrated will signal it to the embedder.

Remark: Although validation is short, but it is not instantaneous, because an HTTP call is required to the corresponding OIDC server, to verify the signature of the token. Do not rely on timeout, but rather accept messages.

After successful token verification, the application is ready to display data.

The nature of inter-process communication between integrated dRofus and embedder differs in each context. Integrated dRofus supports window.postMessage and "redirect-with-parameters" approach. It is possible to implement both in all environments, however, we recommend using messaging in HTML iframe environment and redirect in apps. Workflow details are shown below

1. Messaging

Embedder should pass the token to integrated Drofus by calling the following application server with the following path and hash.備考：のワークフローは、公開されたトークンがある種の攻撃に対して脆弱であるため、現在は非推奨となっています。

トークンの処理はエンベッダーが行います。トークンが見つからない、または無効な場合、dRofus 統合ウェブアプリケーションはエラーメッセージを送信し、起動しません。
エンベッダーは、トークンを保存し、または破棄し、dRofus 統合アプリの起動の間に再ログインすることができます。

エンベッダーは、統合された dRofus環境を作成し、対応する アプリケーション・サーバーのアドレス (application server's address)を以下のパスとハッシュで読み込みますが、
ハッシュには前のステップのトークンが含まれます。

備考：検証は短時間で済みますが、トークンの署名を検証するために対応するOIDCサーバーへのHTTPコールが必要なため、即座には完了しません。
タイムアウトに頼らず、メッセージを受け取ってください。

トークンの検証に成功すると、アプリケーションはデータを表示する準備が整います。

統合dRofusとエンベッダ間のプロセス間通信の性質は、それぞれのコンテキストで異なります。
統合型dRofusは、window.postMessage と、"redirect-with-parameters" アプローチをサポートしています。
いずれの環境でも実装可能ですが、HTML iframe環境ではメッセージングを、アプリ環境ではリダイレクトを利用することを推奨します。ワークフローの詳細を以下に示します。

1. メッセージング

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

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

When token is validated, a message event sent to the embedder's window object. Message payload contains an object called DrofusEmbedded and a successful flag. A successful message is:トークンが認証されると、エンベッダーのウィンドウ・オブジェクトにメッセージが送られます。メッセージのペイロードにはDrofusEmbeddedという、
オブジェクトとsuccessful (成功したフラグ) が含まれます。成功したメッセージは：

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

2.

...

リダイレクト

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

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

When token is validated, the application will redirect to トークンが認証されると、アプリケーションは/embedded/signin-ready, so embedder has to listen to url change events. Query string will indicate if successful and eventuelly include also error message. The successful url is:にリダイレクトするので、エンベッダーはURL変更イベントをリッスンする必要があります。
クエリ文字列は成功したかどうかを示し、場合によってはエラーメッセージも含まれる。成功したURLは：

/embedded/signin-ready?success=true

...

サーバー設定

Anchor
servers servers

...

スタートアップ&

...

コミュニケーション

To start the dRofus Integrated App, one should load the URL into the host iframe or browser widget. The URL is /embedded path on the corresponding application server.

dRofus Integrated App will communicate with the host for multiple occasions: requesting access token or inform about startup process, user navigation or eventual failures. When host receives a token request, it must respond. Every other events are information only

There are two types of communication channel is enabled:

1. In-browser messaging. This is recommended for browser-based web hosts using iframe.

2. Http-based callbacks. This is recommended for non-browser hosts, such as native applications

By default, in-browser messaging is being used. Message format details will be discussed per communication type

In-browser messaging

Messaging provides a secure back-channel between different window objects. More information: dRofus 統合アプリを起動するには、ホストの iframe またはブラウザウィジェットに URL を読み込む必要があります。
URLは /embedded のパスを 対応するアプリケーション・サーバー..

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

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

1. ブラウザ内メッセージング。これは、iframeを使用するブラウザベースのウェブホストに推奨されます。.

2. Httpベースのコールバック。これは、ネイティブアプリケーションのような非ブラウザホストに推奨されます。

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

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

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

In our case, between host’s window and the iframe of dRofus Integrated App. Worth noticing:

...

You can enable messages by adding event listener on its window object

...

Always check the message’s origin property. You may receive messages from others also

...

If you need to reply back, post a message to iframe.contentWindow

...

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

• ウィンドウ・オブジェクトにイベント・リスナーを追加することで、メッセージを有効にすることができます。

• 常にメッセージのオリジン・プロパティをチェックしてください。他の人からのメッセージも受け取る可能性があるかもしれません。

• 返信が必要な場合は、 iframe.contentWindowにメッセージを投稿してください。

• dRofusからの受信メッセージはすべて { DrofusEmbedded: { ... }  } object. オブジェクトの中にラップされます。

...

トークンの取得

dRofus Integrated App requests token by sending a message with requestAccessToken payload and a random string identifier. Message look like this:統合アプリは、requestAccessToken ペイロードとランダムな文字列識別子を含むメッセージを送信することで、
トークンを要求します。メッセージは以下のようになります：

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

Host should reply (in practice post another message), to dRofus Integrated App, the value of the string identifier and access token itself in a following format:ホストは、文字列識別子とアクセストークンの値を以下の形式でdRofus統合アプリに返信（実際には別のメッセージを投稿）する必要があります：

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

Remark: Have access token ready before startup. Token request will timeout after 5 seconds.

...

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

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

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 Integrated App will send informed events once the token is retrieved and eventual error if invalid (for example expired).統合アプリは、トークンが取得されると通知されたイベントを送信し、無効な場合(期限切れなど)はエラーになります。

Http-

...

This is an upcoming feature. Currently in progress, will be documented when finalized.

Http requests are being sent from a browser environment, so several restrictions apply

CORS

Embedders should therefore include CORS-related header in the response and enable request origin, for example:

コールバック

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

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

CORS

したがって、エンベッダーはレスポンスにCORS関連ヘッダーを含め、リクエストのオリジンを有効にする必要があります。
例えば：Access-Control-Allow-Origin: <origin of dRofus Integrated app or *>

Mixed content

...

混合コンテンツ

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

Demo

...

デモ

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

1. HTML

...

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

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

oidc-client-js library: ライブラリ： https://github.com/IdentityModel/oidc-client-js  is being used, but may be also implemented without supporting library  が使用されているが、
サポートライブラリなしで実装されている場合もあります。

2.

...

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

https://code.drofus.com/projects/DC/repos/api.samples/browse/WpfEmbedSample

...

Api

...

This is an upcoming feature. Currently in progress, will be documented when finalized.

dRofus Integrated App will offer searching for different entities on a back-channel. Once finished, front-channel (ie. navigation-based) searches will be deprecated and only displaying entities by id will remain.

Attributes to search in

Rooms

...

Attribute id

...

Description

Showing dRofus content

The content of dRofus integrated application is displayed as a result of either by host's or user’s interaction (i.e. clicking on links). Host controls the content through application URL.

Remark: dRofus integrated application uses Single Page Application-technique for navigation. That means, that the application is loading the HTML-document and assets on startup, and only loads data from the server on user interactions (as in contrast with traditional applications, where the full rendered HTML-document is loaded, where data is blended in). It is often referred as client side navigation. This does not effect the host

The content consists of /embedded path and followed by one frontend URL (as a URL fragment/hash) as listed below.

Idle screen

The content without frontend URL-part or a single # (empty hash) without anything after will result in "idle" screen -- dRofus logo. This is useful to display if nothing else is to be shown It'll be shown /embedded after startup

...

を検索

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

dRofus 統合アプリはバックチャンネルで異なるエンティティの検索を提供します。
完成後、フロントチャンネル (つまり、ナビゲーションベース) の検索は非推奨となり、idによるエンティティの表示のみが残ります。

A検索する属性

部屋

dRofusのコンテンツを表示

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

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

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

アイドル画面

フロントエンドのURL-partがないコンテンツや、#(空のハッシュ)の後に何もないコンテンツは “idle (アイドル) “画面 -- dRofusのロゴ -- になります。
これは何も表示しない場合に便利です。 起動後に /embedded と表示されます。

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

• #/rooms/search?value={searchValue}

  #/rooms/search/{attributeId}?value={searchValue}

  Searches for rooms. If single result, shows the detail panel. If multiple, a selector is shown

  Parameters部屋を検索します。検索結果が1件の場合、詳細パネルを表示します。複数の場合、セレクタが表示されます。

  パラメータ

  • searchValue

    : Defines what to search fro検索対象の定義。

  • attributeId

    : Optional parameter defining which field to search in検索するフィールドを定義するオプションのパラメータ。

• #/rooms/room/{roomId}

  Shows room detail panel

  Parameters部屋の詳細パネルを表示

  パラメータ

  • roomId

    : Drofus room identifier (integer numberdRofus 部屋の識別子 (整数値)

• #/articles/search?value={searchValue}

  #/articles/search/{attributeId}?value={searchValue}

  Searches for items. If single result, shows the detail panel. If multiple, a selector is shown

  Parametersアイテムを検索します。検索結果が1つの場合、詳細パネルを表示します。複数の場合はセレクタが表示されます。

  パラメータ

  • searchValue

    : Defines what to search fro検索対象の定義。

  • attributeId

    : Optional parameter defining which field to search in検索するフィールドを定義するオプションのパラメータ。

• #/articles/article/{articleId}

  Shows item detail panel

  Parametersアイテム詳細パネルを表示。

  パラメータ

  • articleId

    : Drofus article identifier (integer numberdRofusの項目識別子 (整数値)

• #/occurrences/search?value={searchValue}

  #/occurrences/search/{attributeId}?value={searchValue}

  Searches for occurrences. If single result, shows the detail panel. If multiple, a selector is shown

  Parametersオカレンスを検索する。結果が1つの場合、詳細パネルが表示されます。複数の場合はセレクタが表示されます。

  パラメータ

  • searchValue

    : Defines what to search fro検索対象の定義。

  • attributeId

    : Optional parameter defining which field to search in検索するフィールドを定義するオプションのパラメータ。

• #/occurrences/occurrence/{occurrenceId}

  Shows occurrence detail panel

  Parametersオカレンス詳細パネルを表示。

  パラメータ

  • occurrenceId

    : Drofus occurrence identifier (integer numberdRofus オカレンス識別子 (整数値)

...

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

dRofus Web and Integrated App in many cases displays links for relations between entities (i.e. item-occurrence, room-occurrences, etc.). dRofus Integrated App allows the users to follow these links, we refer this as user navigation. If a user navigation occurs, dRofus Integrated App notifies the embedder.

Notification is a message event sent to the embedder's parent window object. Message payload contains the name of destination and parameters (i.e. entity ID).

Remarks:

...

This feature is experimental, and implementation details might be changed on short notice. Actual message format will be added to documentation, once it is settled

...

It is currently not possible to cancel a user navigation by the embedder. 

...

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

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

備考：

1. この機能は実験的なものであり、実装の詳細は急遽変更される可能性がある。実際のメッセージフォーマットは、決まり次第ドキュメントに追加されます。

2. 現在、エンベッダーによるユーザーナビゲーションのキャンセルはできません。

3. 現在の実装では、メッセージベースのワークフローしかサポートしていません。これはHTMLのiframe環境には適していますが、アプリには適していないかもしれません。
   アプリの提案として、エンベッダがHTTPサーバをホストし、そこにdRofus統合アプリがデータをポストする方法があります。
   何かご提案がありましたら、ご連絡ください。