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. Other platforms and browser environments (e.g. WebView on Android, BrowserControl for C#/WPF) are being considered, however, currently not supported.

Remark: This is due to the nature of inter-process communication between integrated dRofus and embedder. In HTML iframe context, messaging can be used. Other platforms may require other communications, eg. redirect to a specific URL. Contact us, if you wish to integrate in app

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 only supports OIDC implicit grant type.

The following parameters are required in such OIDC request:

response_type: token
client_id: drofus-embedded
scope: drofus-web
redirect_uri: has to match one previously registered.
db and pr: 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.

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).

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.

Passing the token

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:

/embedded/signin#access_token=<insert token here>

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.

Application is ready

After the token is received, Drofus integrated application is validating the token. After finished, both successful and unsuccesful, dRofus integrated will send a message to the embedder.

In HTML iframe environment, this means 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 } }

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.

Demo

OIDC is a well-known standard, and many public and free libraries are available for almost all platforms. We are using oidc-client-js library: https://github.com/IdentityModel/oidc-client-js, but may be also implemented without supporting library.
We have created a demo application for your convinience: https://code.drofus.com/projects/BALAZS/repos/embed-demo

Server setup

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!

Client side urls of dRofus integrated application are currently being designed, will be added to this documentation once ready.
J'aimeSoyez le premier à aimer ça

dRofus Wiki

Intégrer le panneau de propriétés Web