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.

...

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

• redirect_uri: your_redirect_uri (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.

2. Code grant with PKCE

The following parameters are required in such OIDC request:

...

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

...

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

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.

...

• #/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)

...