...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
インテグレーション (統合)
dRofus Web は、ホストアプリケーションのアプリケーションスペース内に dRofus のデータパネルを表示することができるエンベッディングによる統合を提供します。
dRofus 統合アプリはブラウザコンテキストで実行され、HTMLiframe を通じて埋め込まれるか、
アプリ内のブラウザウィジェット (例：Android の WebView、C#/WPF の BrowserControl) でで実行されます。
...
統合されたdRofusは、起動パフォーマンスを向上させるためにブラウザキャッシュを使用し、
アプリケーションアセット (html、css、javascript、画像などの静的ファイル)は初回のみ (または変更された場合) 読み込まれ、それ以降の起動はブラウザキャッシュから提供されます。
アプリでこれを利用するには、ブラウザ・ウィジェットのキャッシュが、アプリケーションが終了しても破棄されないことを確認してください。統合されたdRofusは、新しいブラウザタブ/ウィンドウを開く場合があります
(ファイルのダウンロード時、または同じコンテキストでdRofusウェブアプリ全体を開く場合など)。
ブラウザウィジェットのデフォルトの実装は、このような外部ナビゲーション(target="_blank") を無視します。
ホストは、例えばWPF WebViewのNewWindowRequestedイベントのように、このようなイベントを実装して処理する必要があります。
認証とトークン
| Anchor | ||||
|---|---|---|---|---|
|
dRofus のアプリケーションは、Web、デスクトップ共に、ユーザーのログインが必要です。
ログイン時に、ユーザー名、パスワード、プロジェクトの選択が必要です。
プロジェクトの選択は、サーバー、データベース、プロジェクト (データベースに複数設定されている場合) を選択します。
...
備考：トークンは単なる文字列です。JWTトークンを使用しますが、解析する必要はありません。
トークンの取得
各データベースサーバーは、対応するOIDCサーバーインスタンスを持っています。トークンを取得するために、
エンベッダーは選択した OIDC server'(OIDCサーバー) の認証エンドポイントに接続する必要があります。
当社の統合ソリューションは、PKCE タイプの OIDC 暗黙的またはコードグラントに対応しています。コードグラント(code grant)の使用をお勧めします。
登録
エンベッダーは事前にアプリケーションを弊社に登録してください。この登録は現在手動です。
その結果、エンベッダーは、トークン生成時に (クライアントの) アプリケーションを識別するための認証情報を持つことになります。
このような認証情報 (credentials)には、client_id、client_secret（該当する場合）、および1つまたは複数のredirect_uriが含まれます。
1. Implicit grant – Deprecated 
備考： OAuth 2.1標準に準拠し、暗示的なグラントは推奨されません。コードグラントを使用してください。
...
response_type: tokenclient_id: your_client_id(以前に登録された)scope: dr-std embedredirect_uri:your_redirect_uri(以前に登録された)
オプショナル：
dbおよびpr: データベース名とプロジェクト番号 (例："01", "02 "など)。省略された場合、ユーザーは認証後にプロジェクトを選択できるようになります。
リダイレクトURI (“callback URI (コールバックURI) ”とも呼ばれます) は、事前に弊社に登録しておく必要があります。
アプリケーション用に複数のリダイレクトURIを登録することもできます。トークン取得リクエストは、リダイレクトURIを含まなければなりません。
リダイレクトURIは、以前に登録されたURIのいずれかと一致しなければなりません。
2. PKCEによるコード・グラント (Code grant)
このようなOIDCリクエストには以下のパラメータが必要です：
...
dbおよびpr: データベース名とプロジェクト番号 (例："01", "02 "など)。省略された場合、ユーザーは認証後にプロジェクトを選択できるようになります。
ログイン後
ログイン後、ブラウザのセッションは要求されたリダイレクト URI にリダイレクトされます。デフォルトの応答タイプでは、url フラグメントに result が追加されます。
あるいは、フォーム投稿の結果を選択することもできます。トークンは acces_token 結果パラメータにエンコードされます。
ログインに失敗した場合 (エラーまたはユーザーキャンセル)、トークンが含まれていません。
備考：ブラウザ環境では ブラウザ環境ではCORS制限が適用されます。
リダイレクトURIのオリジンを登録しますが、リダイレクトURIとイニシエータのオリジンが異なる場合はお知らせください。
Passing the token
備考：のワークフローは、公開されたトークンがある種の攻撃に対して脆弱であるため、現在は非推奨となっています。
...
エンベッダーは、統合された dRofus環境を作成し、対応する アプリケーション・サーバーのアドレス (application server's address)を以下のパスとハッシュで読み込みますが、
ハッシュには前のステップのトークンが含まれます。
...
統合dRofusとエンベッダ間のプロセス間通信の性質は、それぞれのコンテキストで異なります。
統合型dRofusは、window.postMessage と、"redirect-with-parameters" アプローチをサポートしています。
いずれの環境でも実装可能ですが、HTML iframe環境ではメッセージングを、アプリ環境ではリダイレクトを利用することを推奨します。ワークフローの詳細を以下に示します。
1. メッセージング
エンベッダーは、以下のパスとハッシュで、次のアプリケーションサーバーを呼び出すことにより、統合されたDrofusにトークンを渡す必要があります。
...
トークンが認証されると、エンベッダーのウィンドウ・オブジェクトにメッセージが送られます。メッセージのペイロードにはDrofusEmbeddedという、
オブジェクトとsuccessful (成功したフラグ) が含まれます。成功したメッセージは：
{ "DrofusEmbedded": { "success": true } }
2. リダイレクト
エンベッダーは、以下のパスとハッシュで、次のアプリケーションサーバーを呼び出すことにより、統合されたDrofusにトークンを渡す必要があります。
...
トークンが認証されると、アプリケーションは/embedded/signin-ready,にリダイレクトするので、エンベッダーはURL変更イベントをリッスンする必要があります。
クエリ文字列は成功したかどうかを示し、場合によってはエラーメッセージも含まれる。成功したURLは：
/embedded/signin-ready?success=true
サーバー設定
| Anchor | ||||
|---|---|---|---|---|
|
database | application server | oidc server |
|---|---|---|
db2.nosyko.no | ||
us.drofus.com | ||
eu.drofus.com | ||
uk.drofus.com | ||
ca.drofus.com | ||
au.drofus.com | ||
jp.drofus.com |
スタートアップ& コミュニケーション
dRofus 統合アプリを起動するには、ホストの iframe またはブラウザウィジェットに URL を読み込む必要があります。
URLは /embedded のパスを 対応するアプリケーション・サーバー..
...
デフォルトでは、ブラウザ内のメッセージングが使用されています。メッセージ・フォーマットの詳細については、通信タイプごとに説明します。
ブラウザ内メッセージング
メッセージングは、異なる、window オブジェクト間の安全なバックチャンネルを提供しています。 詳細はこちら： Window.postMessage() - Web APIs | MDN (mozilla.org).
...
ウィンドウ・オブジェクトにイベント・リスナーを追加することで、メッセージを有効にすることができます。
常にメッセージのオリジン・プロパティをチェックしてください。他の人からのメッセージも受け取る可能性があるかもしれません。
返信が必要な場合は、
iframe.contentWindowにメッセージを投稿してください。dRofusからの受信メッセージはすべて
{ DrofusEmbedded: { ... } }オブジェクトの中にラップされます。
トークンの取得
dRofus 統合アプリは、requestAccessToken ペイロードとランダムな文字列識別子を含むメッセージを送信することで、
トークンを要求します。メッセージは以下のようになります：
...
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を通じてコンテンツを制御します。
...
コンテンツは /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 統合アプリはエンベッダーに通知します。
...