@openfin/cloud-interop

This package contains an override that enables Cloud Interop for InteropBroker's unlocking Interop across applications and devices. It is powered by the @openfin/cloud-interop-core-api package which provides an API client to communicate with the Cloud Interop Service.

Overrides are passed to fin.Platform.init when initializing a platform or to fin.Interop.init when creating an InteropBroker directly.

Once overriden the InteropBroker will connect to the given Cloud Interop Service upon initialization. Context will be sent to the Cloud Interop Service when the override broker calls setContext and the broker will also subscribe Context updates from other any other connected brokers in the shared session.

The Cloud Interop Service also supports Intent's. Connected InteropBroker's info calls (handleInfoForIntent, handleInfoForIntentsByContext, fdc3.findIntent, fdc3.findIntentsByContext) will include results for remote sessions and decorate those app identifiers with additional metadata which can then be used to raise Intent's on remote sessions.

Override Options

Option	Type	Description	Default Value	Required
`url`	`string`	URL of the Cloud Interop service	N/A	Yes
`platformId`	`string`	Platform ID	N/A	Yes
`sourceId`	`string`	Source ID	N/A	Yes
`reconnectRetryLimit`	`number` (optional)	Limit for reconnect retries	N/A	No
`keepAliveIntervalSeconds`	`number` (optional)	Interval in seconds to keep the connection alive	N/A	No
`findIntentTimeout`	`number` (optional)	How long to wait for connected clients to respond. Do not make this too high.	`3 seconds`	No
`authenticationType`	`'jwt' \| 'basic' \| 'default'` (optional)	Type of authentication to use	N/A	No
`basicAuthenticationParameters`	`{ username: string, password: string }` (optional)	Parameters for basic authentication	N/A	No
`jwtAuthenticationParameters`	`{ jwtRequestCallback: () => string \| object, authenticationId: string }` (optional)	Parameters for JWT authentication	N/A	No
`logger`	`(logLevel: 'log' \| 'debug' \| 'info' \| 'warn' \| 'error', message: string, ...args: unknown[]) => void` (optional)	If provided, will defer to this logger, otherwise logs to `console.debug`, reduced by LogLevel	`console.debug`	No
`logLevel`	`'log' \| 'debug' \| 'info' \| 'warn' \| 'error'` (optional)	The level at which cloud-interop override will log.	`'warn'`	No

Usage

In a Platform with other overrides:

import { cloudInteropOverride } from "@openfin/cloud-interop";
import { ExampleOverride } from "./example";

const cloudConfig = {
  url: "<CLOUD_INTEROP_SERVICE_URL>",
  platformId: "my-platform", // Shared identifier for apps that should communicate
  sourceId: "my-desktop"
};

const InitializedCloudInteropOverride = await cloudInteropOverride(cloudConfig);

// Ordering is important, ensure Cloud Interop Override is at the end of the list to send overriden Context to the cloud
await fin.Platform.init({
  interopOverride: [ExampleOverride, InitializedCloudInteropOverride],
});

When creating an InteropBroker directly:

import { cloudInteropOverride } from "@openfin/cloud-interop";

const cloudConfig = {
  url: "<CLOUD_INTEROP_SERVICE_URL>",
  platformId: "my-platform", // Shared identifier for apps that should communicate
  sourceId: "my-desktop"
};

const InitializedCloudInteropOverride = await cloudInteropOverride(cloudConfig);

await fin.Interop.init(fin.me.uuid, InitializedCloudInteropOverride);

Authentication

The Cloud Interop API client offers various authentication methods which can be enabled through configuration.

Interactive session based authentication using cookies (default):

import { cloudInteropOverride } from "@openfin/cloud-interop";

const cloudConfig = {
  url: "<CLOUD_INTEROP_SERVICE_URL>",
  platformId: "my-platform", // Shared identifier for apps that should communicate
  sourceId: "my-desktop",
};

const InitializedCloudInteropOverride = await cloudInteropOverride(cloudConfig);

Basic authentication with credentials provisioned per Cloud Interop Service:

import { cloudInteropOverride } from "@openfin/cloud-interop";

const cloudConfig = {
  url: "<CLOUD_INTEROP_SERVICE_URL>",
  platformId: "my-platform", // Shared identifier for apps that should communicate
  sourceId: "my-desktop",
  authenticationType: "basic",
  basicAuthenticationParameters: {
    username: "bob@acme.com",
    password: "password"
  }
};

const InitializedCloudInteropOverride = await cloudInteropOverride(cloudConfig);

JWT token authentication:

import { cloudInteropOverride } from "@openfin/cloud-interop";

const cloudConfig = {
  url: "<CLOUD_INTEROP_SERVICE_URL>",
  platformId: "my-platform", // Shared identifier for apps that should communicate
  sourceId: "my-desktop",
  authenticationType: "jwt",
  jwtAuthenticationParameters: {
    // Service Gateway authentication identifier, contact Here support to obtain id for your organization. 
    authenticationId: "00b671f2-e1a9-4c29-9fa9-55f1988a11fb",
    // Callback invoked whenever a jwt token is required for a request
    jwtRequestCallback: () => "my-token"
  }
};

const InitializedCloudInteropOverride = await cloudInteropOverride(cloudConfig);