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

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

アプリの備考

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

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

認証とトークン

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

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

1. エンベッダーは有効なトークンを持っていなければなりません。

2. dRofusの統合アプリケーションは、ホストからトークンを取得する必要がある場合、それを実行します。

3. 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標準に準拠し、暗示的なグラントは推奨されません。コードグラントを使用してください。

このような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: KCEのコードチャレンジを送信。

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

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

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

ログイン後

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

備考：ブラウザ環境では ブラウザ環境では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.

/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": { "success": true } }

2. Redirect

Embedder should pass the token to integrated Drofus by calling the following application server with the following path and hash.

/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:

/embedded/signin-ready?success=true

Server setup

Startup & communication

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: 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

• All incoming messages from dRofus are wrapped inside of { DrofusEmbedded: { ... }  } object.

Fetching token

dRofus Integrated App requests token by sending a message with requestAccessToken payload and a random string identifier. Message look like this:

{ 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:

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

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

The following snippet shows an example how to handle such requests

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-callbacks

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:

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

Mixed content

dRofus Integrated App is being served over HTTPS. For security reasons, browsers reject outgoing Http calls of mixed content (when a secure site requests unsecure resources). In practice, browsers would only allow callbacks via HTTPS protocol. Some browser also consider loopback over HTTP as secure, for example “http://localhost:8080”. More information: Mixed content - Web security | MDN (mozilla.org)

Demo

OIDC is a well-known standard, and many public and free libraries are available for almost all platforms.
We have created a demo applications for your convenience

1. HTML iframe, implicit grant, messaging

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. App, code grant, redirect

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

Search 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

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

Allowed frontend Urls

• #/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

  • 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 number)

• #/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

  • 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 number)

• #/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

  • 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 number)

User navigation

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:

1. 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

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

3. The current implementation only supports message-based workflow, which aligns well with HTML iframe environment, however might be inconvinient for apps. One proposal for apps would be that embedder hosts an HTTP-server, which dRofus Integrated App would post data to. Please contact us if you have a proposal.