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

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

dRofus Webは、埋め込みによる統合機能を備えており、ホストアプリケーションはアプリケーション画面内にdRofusのデータパネルを表示することができます。
dRofus Integrated Appはブラウザ環境で動作し、HTMLのiframeを介して埋め込まれるか、アプリ内のブラウザウィジェット（例：AndroidのWebView、C#/WPF用のBrowserControl）で実行されることが想定されています。

アプリの備考

統合されたdRofusは、起動パフォーマンスを向上させるためにブラウザのキャッシュを利用しています。アプリケーションのアセット（HTML、CSS、JavaScript、画像などの静的ファイル）は初回のみ（または変更があった場合のみ）読み込まれ、その後の起動時にはブラウザのキャッシュから提供されます。アプリでこの機能を利用するには、アプリケーションを閉じた際にブラウザウィジェットのキャッシュが破棄されないようにしてください。
場合によっては、統合されたdRofusが新しいブラウザタブやウィンドウを開くことがあります（ファイルのダウンロード時や、同じコンテキストでdRofusのフルWebアプリを開く場合など）。ブラウザウィジェットのデフォルトの実装では、このような外部へのナビゲーション（target="_blank"）は無視されます。そのため、ホスト側でこのようなイベントを実装し、処理する必要があります。例えば、WPF WebViewのNewWindowRequestedイベントなどが該当します。

認証とトークン

dRofusのアプリケーションは、Web版・デスクトップ版を問わず、ログインが必要です。ログイン時には、ユーザー名、パスワード、およびプロジェクトの選択が必要です。プロジェクトの選択には、サーバー、データベース、およびプロジェクト（データベース内に複数のプロジェクトが設定されている場合）の選択が含まれます。

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

エンベッダーは有効なトークンを保有している必要があります。保有していない場合は、新しいトークンを取得する必要があります
dRofus統合アプリケーションは、トークンが必要になった際に、ホストからトークンを取得し始めます。
dRofus統合アプリケーションはトークンを検証し、ホストに通知します。

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

トークンの取得

各データベースサーバーには、対応するOIDCサーバーインスタンスがあります。トークンを取得するには、エンベッダーは指定されたOIDC server'(OIDCサーバー) の認可エンドポイントに接続する必要があります。当社の統合ソリューションは、PKCEタイプを使用したOIDCのImplicit (暗黙的フロー) とCode Grant (コードフロー) に対応しています。コードグラントの使用を推奨します。

登録

エンベッダーは、事前に当社へアプリケーションを登録する必要があります。現在、この登録は手動で行われています。その結果、エンベッダーには、トークン取得時に（クライアント）アプリケーションを識別するための一連の認証情報が付与されます。これらの認証情報には、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) ”とも呼ばれる) は、事前に弊社に登録しておく必要があります。また、1つのアプリケーションに対して複数のリダイレクト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の重要度は低く、実際のWebサイトを指す必要はなく、任意のURIを使用できます。ただし、それでも入力が必要であり、事前に登録されたものと一致している必要があります

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

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

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

ログイン後

ログイン後、ブラウザのセッションは指定されたリダイレクトURIへ転送されます。デフォルトの応答タイプとして、結果がURLのフラグメントに追加されます。あるいは、フォームのPOST結果を選択することも可能です。トークンは、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 サーバー
no.drofus.com	https://app-no.drofus.com	https://ids-no.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統合アプリがデータをポストする方法があります。
何かご提案がありましたら、ご連絡ください。