# Embedded Connection Widget

The Embedded Connection Widget allows the end customer to access and authenticate the app connections in their account. It allows Workato Embedded partners to build their own user experience for their customers to provide authentication to connections.

It usually functions well in Blackbox use cases where the Workato Embedded partner builds and maintains integrations on the customer's behalf. In this scenario, the customer can use the widget to authenticate connections required for their recipes from the partner's application, without ever having to leave and access the Workato platform.

This is available as an add-on to all Workato Embedded partners.

# Implementation

To use the Connection Widget you can add:

<iframe src="https://wwww.workato.com/direct_link/embedded/connections/<connection_id>>?workato_dl_token=<jwt_token>"></iframe>

The Connection Widget API works on PostMessage API (opens new window) in the following format:

{ type: string, payload: object }

Note:

If you are testing the Widget for the first time, please provide your Workato customer success representative the Origin URL. This will allow the window to receive the messages via the PostMessage API.

# Supported PostMessages

The following PostMessages are sent from Workato (the IFrame) to the partner application to assist in rendering different UI states for the embedded connection widget window.

Type Payload Description
heightChange { height: number } Content height was changed. This allows the implemented widget window to be extended for seamless transitions when this occurs.
connectionStatusChange { id: number, provider: string, connected?: boolean, error?: string } Connection status was changed (eg. Connected to Disconnected).
error { message: string } Error message

# Example

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <script>
      window.addEventListener('message', receiveMessage);
      function receiveMessage(event) {
        var data = JSON.parse(event.data);

        switch (data.type) {
          case 'heightChange':
            document.getElementById('workatoId').style.height = data.payload.height + 'px';
            break;
          case 'connectionStatusChange':
            var message = data.error || (data.payload.connected ? 'Connected' : 'Disconnected');
            document.getElementById('statusId').innerText = message;
            break;
          case 'error':
            console.log(data.payload.message);
        }
      }
    </script>
  </head>
  <body>
    <h4>Status: <span id="statusId"></span></h4>
    <iframe id="workatoId" src="https://www.workato.com/direct_link/embedded/connections/<connection_id>>?workato_dl_token=<token>" style="width: 500px; height: 150px; border: 0"></iframe>
  </body>
</html>

# JWT direct linking

Every customer account that uses the Embedded Connection Widget is authenticated to their corresponding Workato account through JWT direct linking. This allows access to the secured resources (Connections) within specific customer accounts.

# Example of JWT generation:

import nanoid from 'nanoid';
import {sign} from 'jsonwebtoken';

/**
* @param WorkatoEmbeddedapiKey A unique key associated with the partner's account. This is provided by Workato.
* @param customerAccountId ID of the customer's account. This is returned when the customer account is created.
* @param privateKey Private key using RS256 algorithm (This should match the public key provided to Workato).
*/
function getToken(WorkatoEmbeddedapiKey, customerAccountId, privateKey) {
  return sign({
    sub: `${WorkatoEmbeddedapiKey}:${customerAccountId}`,
    jti: nanoid()
  },
  privateKey,
  {
    algorithm: 'RS256'
  });
}

See more examples at https://github.com/auth0/node-jsonwebtoken (opens new window).