Integration
dRofus web application offers integration through embedding, in which the embedder clients can display dRofus data panels inside their application space. dRofus integrated application 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"
) Embedders should implement then handle such event, for example in WPF WebView,NewWindowRequested
event.
Login and startup
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).
Login to dRofus integrated application relies on OIDC-standard. The following steps summarizes the login workflow:
- Embedder fetches token from Drofus OIDC server
- Embedder passes fetched token to dRofus application server
- dRofus integrated application verifies the token and notifies embedder
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, so to fetch a token, embedder should connect to a chosen OIDC server's authorize endpoint. Our integrating solution supports OIDC implicit or code grant type. We recommend using implicit in browser web application and code in desktop/mobile apps.
1. Implicit grant
The following parameters are required in such OIDC request:
response_type: token
client_id: drofus-embedded
scope: dr-std
redirect_uri
: has to match one previously registered.db
andpr
: database name and project number (eg, "01", "02", etc.). These are not standard OIDC parameters, but required by Drofus login procedure.
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
The following parameters are required in such OIDC request:
response_type: code
client_id: drofus-embedded-app
client_secret:
Contact us and will provide youscope: dr-std
redirect_uri
:http://localhost:5678/landing
or has to match one 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
db
andpr
: database name and project number (eg, "01", "02", etc.). These are not standard OIDC parameters, but required by Drofus login procedure.
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
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 application.
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 application 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
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 convinience
1. HTML iframe, implicit grant, messaging
https://code.drofus.com/projects/BALAZS/repos/embed-demo
oidc-client-js library: https://github.com/IdentityModel/oidc-client-js is being used, but may be also implemented without supporting library
2. App, code grant, redirect
https://code.drofus.com/projects/DC/repos/api.samples/browse/WpfEmbedSample
Server setup
database | application server | oidc server |
---|---|---|
db2.nosyko.no | https://app-db2.drofus.com | https://ids-db2.drofus.com |
oslt2 | https://app-oslt2.drofus.com | https://ids-oslt2.drofus.com |
Displaying the desired panel
dRofus integrated application can be controlled through it's 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.
The path of entry point to our dRofus integrated application is: /embedded on the corresponding application server. Application requires a logged in user, please do login first!
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
- : Defines what to search fro
- : Optional parameter defining which field to search in
#/rooms/room/{roomId}
Shows room detail panel
Parameters
- : 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
- : Defines what to search fro
- : Optional parameter defining which field to search in
#/articles/article/{articleId}
Shows item detail panel
Parameters
- : 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
- : Defines what to search fro
- : Optional parameter defining which field to search in
#/occurrences/occurrence/{occurrenceId}
Shows occurrence detail panel
Parameters
- : Drofus occurrence identifier (integer number)