Integrate web property panel in your application
Integration
dRofus Web offers integration through embedding, in which the host application can display dRofus data panels inside their application space. dRofus Integrated App runs in a browser context and expected to be embedded through HTML iframe
or run in a browser widget (e.g. WebView on Android, BrowserControl for C#/WPF) in app.
Remarks for apps
integrated dRofus uses browser cache to boost startup performance, application assets (static files like html, css, javascript, images, etc.) are only being loaded first time (or if changed) and subsequent startups are being served from browser cache. To utilize this in apps, make sure browser widget cache is not being discarded if the application is closed.
In some cases, integrated dRofus opens a new browser tab/window (when downloading files or opening the full dRofus webapp with the same context). Browser widgets default implementation is ignoring such external navigation (
target="_blank"
) Host should implement then handle such event, for example in WPF WebView,NewWindowRequested
event.
Authentication and token
dRofus applications, both web and desktop, require a logged in user. At login, username, password and project selection is required. Project selection consists of selecting server, database and project (if multiple configured in a database).
Authentication required by dRofus Integrated App relies on OIDC-standard. The following steps summarizes the login workflow:
Embedder should posess a valid token, if not, it may fetch a new one
dRofus integrated application will initiate pulling the token from the host, when it requires it
dRofus integrated application verifies the token and notifies the host
Remark: Token is just a string. We use JWT token, but you do not need to parse it.
Fetching the token
Each database server has a corresponding OIDC server instance. For fetching a token, Embedder should connect to a chosen OIDC server's authorize endpoint. Our integrating solution supports OIDC implicit or code grant with PKCE type. We recommend using code grant.
Registration
Embedders should register their application with us beforehand. This registration is currently manual. As a result, embedders will have a set of credentials which will identify (client) application during token henting. Such credentials include client_id, client_secret (if applicable) and one or multiple redirect_uri.
1. Implicit grant – Deprecated
Remark: In accordance with OAuth 2.1 standard, implicit grant is not recommend. Please use code grant
The following parameters are required in such OIDC request:
response_type: token
client_id: your_client_id
(previously registered)scope: dr-std embed
redirect_uri
:your_redirect_uri
(previously registered)
Optional:
db
andpr
: database name and project number (eg, "01", "02", etc.). If omitted, a user will be allowed to select project after authentication.
Redirect URI (may also be referred as "callback URI") must be registered with us beforehand. You may also register multiple redirect URIs for your application. The token fetching request must include the redirect URI, which must match any of the previously registered URIs.
2. Code grant with PKCE
The following parameters are required in such OIDC request:
response_type: code
client_id: your_client_id
(previously registered)client_secret: your_client_secret
(as cleartext, previously registered)scope: dr-std embed
redirect_uri
: your redirect URI (previously registered)
Remark: If code grant is used in a web application, redirect_uri
must be a valid URL pointing to a web application the embedders control and thus has to be registered same way as with implicit grant. Redirect URI has less importance in apps and any URI can be used, does not need to point to an actual website. But still, must be filled and match previously registered one
code_challenge:
sends the code challenge for PKCEcode_challenge_method:
sends challenge method for PKCE,S256
(indicating SHA256) must be set
Optional parameters:
db
andpr
: database name and project number (eg, "01", "02", etc.). If omitted, a user will be allowed to select project after authentication.
After login
After login, the browser session will be redirected to the requested redirect URI. As of default response type, result is added to the url fragment. Alternatively, form post result can be chosen. Token is encoded into the acces_token
result parameter. Unsuccessful login (error or user cancellation) does not contain token.
Remark: In browser environment CORS restrictions apply. We register the origin of the redirect URI(s), but please let us know, if the initiator origin differs from the redirect URI(s).
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
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 |
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:
In-browser messaging. This is recommended for browser-based web hosts using
iframe
.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
Browse balazs / embed-demo - dRofus Bitbucket
oidc-client-js library: GitHub - IdentityModel/oidc-client-js: OpenID Connect (OIDC) and OAuth2 protocol support for browser-based JavaScript applications is being used, but may be also implemented without supporting library
2. App, code grant, redirect
Browse dRofus COMMON / Api.Samples - dRofus Bitbucket
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
Attribute id | Description |
---|---|
|
|
|
|
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:
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
It is currently not possible to cancel a user navigation by the embedder.
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.