External Authentication Configuration for Embedded Applications
- Maciej Zabielski
Since 5.1.0
Overview
When integrating the application as an embedded component, the host system can provide its own authentication context instead of using the application's default authentication mechanism. This document explains how to configure and implement external authentication.
In this way your host application can obtain the same user context in the integrated system.
Requirements
The application requires a function that can provide valid authentication tokens. These tokens are typically obtained through machine-to-machine (M2M) connections, such as token exchange mechanisms.
The minimal required response format is:
{
access_token: "eyJhbG..."
}Currently, only the access_token field is mandatory. The application will automatically request a new token when the current one expires.
For future compatibility, the authentication system supports a more comprehensive payload structure:
{
access_token: "eyJhbG...",
expires_in: 7200,
refresh_expires_in: 1800,
refresh_token : "..2rgOShce-sA\",
token_type: "Bearer",
not-before-policy: 0,
session_state: "25127dc7-315b-4fb5-9bb5-625ff09e1b29",
scope: "email profile security-schema",
contentType: "application/json"
}FMA in the “external auth” mode will request a new token automatically as soon as the one in use expired.
Please set a reasonable expiry time on the token. FMA assumes a token needs to be replaced if its validity period is below 15 seconds. Higher expiry values will also reduce a number of complex authentication calls made by the system.
Implementation Guide
Preventing Default Authentication
To prevent the application from launching with its default authentication service redirect, initialize it with the awaitConfig parameter:
https://localhost:8080/client/?awaitConfig=trueThis will perform basic initialization while waiting for your custom configuration.
Configuration Setup
The application exposes a global promise hdcReadyForConfig that signals when it's ready to receive custom configuration. You can access this promise using the following pattern:
Once the promise resolves, you can configure the application and start it using:
Example Implementation
This implementation demonstrates setting up an asynchronous token provider that your host application can use to supply authentication tokens to the embedded application.
Embedding in iFrame
When host system is using an iFrame to embed our application, a direct code execution might not be allowed inside of the frame scope. In that case systems can communicate via messages.
A host system messages handling should implement subscription to messages:
For the full working sample, please access this address on your instance (replace localhost with your instance): http://localhost:8080/client/messageAuthTester.html
This example is using FMA anonymous auth token service that must be enabled for this test to work. Its not intended for production use and should be replaced by a proper backend logic for fetching a token between your backend system and FMA auth server.
In order to implement that, create a machine2machine client and use “token exchange” in order to obtain a valid token for your user.
Summary of the most important steps showcased in the messageAuthTester.html:
Setup environment for FMA app:
create an iframe element for FMA app
implement
fetchTokenForHdc- this function should make an API call to your backend (not FMA) to fetch a token for your userimplement message subscription to listen for events from FMA app
when your page is ready (e.g. after
DOMContentLoadedevent), initialize a message handler (window.addEventListener('message', async (event))Load the FMA app in the iframe, make sure that the url contains a query parameter:
?awaitConfig=trueawait message:
HDC_APP_READY_FOR_CONFIG, send config messages and start the app:HDC_ENABLE_EXTERNAL_AUTHHDC_START_APP
be ready to handle message:
HDC_AUTH_TOKEN_REQUESTrespond with
HDC_AUTH_TOKEN_RESPONSEyour system should respond in max 20 seconds