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

インテグレーション

dRofusのWebアプリケーションは、埋め込みによる統合を提供しており、埋め込みクライアントは、自分のアプリケーションスペース内にdRofusのデータパネルを表示することができます。dRofus統合アプリケーションは、ブラウザコンテキストで動作し、HTML iframeを介して埋め込まれるか、アプリ内のブラウザウィジェット (例：Android上のWebView、C#/WPFのBrowserControl) で動作することが想定されています。

cefEQFEWFG2RG WRG THJW TRHJTR HT HQR dwd wd wd w we

アプリの備考

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

ログインと起動

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

dRofus 統合アプリケーションへのログインは、OIDC 規格に準拠しています。以下の手順でログインのワークフローをまとめました :

エンベッダーはdRofus OIDCサーバからトークンを取得します。
エンベッダーは取得したトークンをdRofusアプリケーションサーバーに渡します。
dRofus統合アプリケーションがトークンを検証し、エンベンダーに通知します。

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

トークンの取得

各データベースサーバーは対応するOIDCサーバーインスタンスを持っているので、トークンを取得するには、埋め込み機能は選択したOIDCサーバーの認証エンドポイントに接続する必要があります。

登録

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

1. インプリシットグラント

このようなOIDC要求では、次のパラメータが必要です :

response_type: token
client_id: your_client_id (以前に登録済)
scope: dr-std
redirect_uri: your_redirect_uri (以前に登録済)
db と pr: データベース名とプロジェクト番号 (例: "01", "02", など). これらはOIDCの標準的なパラメータではありませんが、dRofusのログイン手順で必要となります。

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

2. コードの付与

このようなOIDC要求では、次のパラメータが必要です :

response_type: code
client_id: your_client_id (以前に登録済)
client_secret: your_client_secret (クリアテキストとして、以前に登録済)
scope: dr-std
redirect_uri: your_redirect_uri (以前に登録済)

備考 : Web アプリケーションでコードグラントを使用する場合、 redirect_uri はエンベッダーがコントロールする Web アプリケーションを指す有効な URL でなければならず、インプリシットグラントと同じ方法で登録する必要があります。アプリの場合、リダイレクトURIの重要性は低く、実際のWebサイトを指す必要はなく、どのようなURIでも使用できます。ただし、事前に登録したものと一致する必要があります。

db と pr: データベース名とプロジェクト番号（例："01"、"02 "など）。これらはOIDCの標準パラメータではありませんが、dRofusのログイン手順で必要となります。

ログイン後

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

備考 : ブラウザ環境ではCORSの制約があります。リダイレクトURIのオリジンを登録しますが、リダイレクトURIとイニシエータのオリジンが異なる場合は、お伝えください。

トークンの受渡し

エンベッダーは、トークンの取り扱いに責任を持ちます。。トークンがない場合、または無効な場合、dRofus統合アプリケーションはエラーメッセージを送信し、起動しません。エンベッダーは、トークンを保存したり、破棄したり、dRofus統合アプリケーションの起動時に再ログインすることができます。

エンベッダーは統合されたdRofus環境を作成し、対応するアプリケーションサーバのアドレスを次のパスとハッシュで読み込みます。ハッシュには、前のステップのトークンが含まれています。トークンを受け取った後、drofus統合アプリケーションはトークンのバリデーションを行います。成功・失敗の両方の検証が行われると、dRofus統合はエンベンダーにそれを通知します。

備考: 検証は短時間で終わりますが、即効性があるわけではありません。、なぜなら、トークンの署名を検証するために、対応する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はよく知られた規格であり、多くの公開・無償ライブラリがほぼすべてのプラットフォームで利用可能です。
デモアプリケーションを作成しましたので、ご覧ください。

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

サーバー設定

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

dRofusのコンテンツを表示

アプリケーションにはログインしているユーザーが必要です。最初にログインしてください! dRofus統合アプリケーションのコンテンツは、エンベッダーの制御またはユーザーの操作(リンクのクリック)によって表示されます。エンベッダーは、アプリケーションのURLを通じてコンテンツを制御します。

備考: dRofus統合アプリケーションは、ナビゲーションにシングルページアプリケーションテクニックを使用します。つまり、アプリケーションは起動時にHTMLドキュメントとアセットを読み込み、ユーザーの操作に応じてサーバーからデータを読み込むだけです。(従来のアプリケーションとは対照的に、完全にレンダリングされたHTMLドキュメントが読み込まれ、データはそこに紛れ込みます) クライアントサイドナビゲーションと呼ばれることもあります。これは、エンベッダーに影響を与えません。

dRofus統合アプリケーションのURLは、対応するアプリケーションサーバーの /embeddedパスと、それに続く1つのフロントエンドのURL (URLフラグメント/ハッシュとして) であり、以下に記載されています。

フロントエンドの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の統合アプリケーションがデータをポストするというものがあります。ご提案があれば、ぜひご連絡ください。