Static authentication

There are 2 kinds of authentication: static and dynamic. You’re already familiar with them even if you don’t know the names. Static authentication uses a specific authenticator, such as a password or PIN. It is called static because the authenticator is reused multiple times and stays the same until you change it. In contrast, in dynamic authentication a separate authenticator is generated for every session and nothing is ever reused.

Finsemble supports both static and dynamic authentication, but it uses them in different situations. For most apps, we use dynamic authentication. When Finsemble launches an app, the windowService automatically creates an authentication token for authenticating an application’s fdc3 client. This happens within Finsemble without you having to do anything special.

But there is one kind of app that Finsemble doesn't launch. We call these freestanding apps, and they can be either native or web. Because windowService isn’t involved in the launching process, there is no mechanism to provide a dynamic token. As a result, for these apps, dynamic authentication is not an option. Instead, you must provide a private key to enable Finsemble to build a static authentication token. Let’s look at an example of a simple freestanding web app that invokes an FDC3 broadcast when a user presses a button. The key part of this example is the startup portion, where during app initialization you must invoke FDCL.startApp(), providing a unique window name, a unique app name, and a private digitalSigningKey for authentication.

<button onclick="broadcast()">Broadcast</button>

For static authentication we need a pair of keys, one private and one public. You use one key for creating a signature, and the other key for verifying the authenticity of that signature. We show you how to included the private key in the code we’ve just seen. You must add the public key to Finsemble’s config file.

Let’s now look at how to generate such a pair of keys. Don’t worry, you don’t need to be an expert at cryptography to use this kind of authentication, but check out Electronic authentication to learn more about authentication and authorization.

Generating key pairs for static authentication

In Finsemble, you use the private key for creating the signature within the app and the public key for verifying the signature in Finsemble’s Interop Service. You must provide the private signing key, digitalSigningKey, during startup (as shown in our example). You must place the corresponding public key in the app’s appD config. The InteropService gets this key from appD to verify the static authentication token included in the FDC3 client’s register message.

You can create a unique key pair (the private digitalSigningKey and its corresponding public key) by invoking FSBL.createKeys() from the Chromium Developer Tools console of any Finsemble application. The easiest way to open the console is to click a a Finsemble app to bring it into focus and then press CTRL+SHIFT+I while Finsemble is running.

Caution: If you open the Developer Tools console from your freestanding app or a web browser that Finsemble doesn't know about, and then try to invoke FSBL.createKeys() you will get an uncaught reference error.

Here is an example, where we entered FSBL.createKeys()at the console.


After you generate the keys, you can copy each to the clipboard by typing copy(FSBLPrivateKey) or copy(FSBLPrivateKey). You can then paste it into the appropriate location. This figure shows the private key, which FSBL.createKeys() stores in the window variable FSBLPrivateKey, being copied to the clipboard.


From the clipboard you can copy the key into the app's code to set the digitalSigningKey property passed into FSBL.startApp, as here:


Next, you put the public key into the app's AppD config file within Finsemble. In the same Dev Tools console session, as shown in the next figure, after you have copied the private key, you can copy the public key FSBLPublicKey to the clipboard:


From the clipboard paste the contents of FSBLPublicKey into the manifest.signtureKey property within the app's appD entry in config. Here is the AppD entry with the signature key pasted into the signatureKey property.


Caution: Caution When you paste from the clipboard into a JSON file, make sure that each property name within the keys is enclosed in quotes (e.g. alg must become "alg"). Some editors might do it semi-automatically.

See also

Electronic authentication