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

このような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

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

トークンの処理はエンベッダーが行います。トークンが見つからない、または無効な場合、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>

トークンが認証されると、エンベッダーのウィンドウ・オブジェクトにメッセージが送られます。メッセージのペイロードには 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
us.drofus.com	https://web-us.drofus.com	https://ids-us.drofus.com
eu.drofus.com	https://web-eu.drofus.com	https://ids-eu.drofus.com
uk.drofus.com	https://web-uk.drofus.com	https://ids-uk.drofus.com
ca.drofus.com	https://web-ca.drofus.com	https://ids-ca.drofus.com
au.drofus.com	https://web-au.drofus.com	https://ids-au.drofus.com
jp.drofus.com	https://web-jp.drofus.com	https://ids-jp.drofus.com

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

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

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

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

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

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

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

メッセージングは、異なる、window オブジェクト間の安全なバックチャンネルを提供しています。詳細はこちら： Window.postMessage() - Web APIs | 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経由のループバックを安全なものとみなすものもあります。
詳細はこちら：混合コンテンツ - Webセキュリティ｜MDN (mozilla.org)

デモ

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

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

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

oidc-client-js ライブラリ： https://github.com/IdentityModel/oidc-client-js が使用されているが、
サポートライブラリなしで実装されている場合もあります。

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

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

Api を検索

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

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

検索する属性

部屋

属性 id	説明

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}
部屋を検索します。検索結果が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統合アプリがデータをポストする方法があります。
何かご提案がありましたら、ご連絡ください。