@axa-ch/bifrost
v8.1.0
Published
integration framework for aem
Downloads
43
Readme
Bifröst - a useful AEM integration framework
An integration framework for AEM. It's like a multicolored bridge between SPAs and AEM, hence the name from Nordic mythology. It will provide a localhost dev environment for SPAs and integration interfaces so that they can run inside a multi-SPA enviroment
Detailed documentation can be found here: https://confluence.axa.com/confluence/x/4samCw
Requirements
The client SPAs have to be able to deal with standard ES6 modules.
Authorisation
Bifrost offers three methods used under the hood to provide your POD's SPA with an Access Token:
<iframe>
- Redirect
- XMLHttpRequest
Iframe
This method does not leave your POD's page, instead an authorization <iframe>
is overlaid over the whole page and prompts the user for login.
Redirect
This method leaves your POD's page and redirects to an authorization page to prompt the user for login.
XMLHttpRequest
This method performs an asynchronous network request to authorise you POD.
Dev stuff
To start the mocking API, please run npm run api
. The default port is 8080
. If you need another port to be served, say port 3000, please run npm run api port=3000
Inactivity detection and auto-logout
Whereas login is used deliberately to provide your POD's SPA with an Access Token, logout sometimes happens involuntarily. This is due to requirements from AXA IT security. A number of user activities (scrolling, resizing, keyboard use, mouse use, touch) counts as user activity. The absence of such user activity for some time triggers inactivity detection. Another direct trigger of inactivity is leaving the active browser tab or window. When inactivity has been detected for some time, an automatic logout is performed, thus revoking the Access Token.
How can a POD be notified on logout
As per the previous section, automatic logout can happen after some time of inactivity. Sometimes a POD needs to react to such automatic logout, e.g. perhaps to invalidate its own legacy session tokens. The idea here is to subscribe to a bifrost store key that is characteristic for logged-in status, and get called back when that key is deleted as a result of logout. A code snippet illustrates this idea, using the key login
in namespace common
:
const { subscribe } = store; // bifrost store
subscribe(
"login",
"common",
(_oldValue, reason) => {
// does it look like we were just logged out?
if (reason === "clean") {
// yes, invalidate our own legacy session tokens, or similar
}
},
true // true: get called back when that key-namespace combination is cleaned (which happens on logout)
);
Store
Bifrost implements an immutable store for communication between PODs. It is important to know that bifrost creates a deep clone when a new entry is added to the store and also when someone gets an entry from the store. This is important so that consumer and provider can change their value of type object
without having object-reference-based side effects.
On every store entry, the entry is persisted to browser session storage. This feature is very handy if a page refresh happens on the store. Be aware that usage of browser local storage on the other hand is highly questionable and has to be double-checked with AXA IT security on a case-by-case basis. For this reason, bifrost does not provide an API persisting to browser local storage. If someone has the OK from security and can use local storage, please make a entry key that is unique, like so: [ANY-HASH]-key-name
. Also, there must be an implementation that cleans local storage entries when the user revisits.
When publishing a value under a key:
- scalar and array values are overwritten in-place
- objects values are merged with their in-store value (to be discussed: should we keep this behavior?)
API under POD Menu Manager
The POD Menu Manager uses the bifrost store
for communication. The API is described here: https://github.com/axa-ch/pod-menu-manager/blob/develop/DOCUMENTATION.md
Store API
When creating a new POD with the latest create-pod-app a mock store is available. In the devonly.js
, which is created dynamically when running create-pod-app, you can mock external PODs. You will find more details in the devonly.js
.
Every entry refers to a namespace. The default namespace is "common".
The store that is injected into the POD's options parameter (i.e. arg. 2 of the POD constructor) has the following API:
{
// gets the value of an entry. if no namespace is passed, it gets it from common
get ( entry: string [, namespace: string] ) : any,
// adds a new value for an entry to a namespace in the store and calls all subscribers to the given entry in the same namespace. If persist is passed as "false", session Storage sync will be disabled
publish ( entry: string, namespace: string, value: any, persist = true: boolean ) : boolean,
// the callback function cb is called with the value for a given entry when for the same entry / namespace combination a publish() has been executed
// (if onClean is truthy, also when a clean() is executed)
subscribe ( entry: string, namespace: string, cb: Function(value: any), onClean: boolean ) : boolean,
// deletes the given entry in a namespace and its value from the store
clean ( entry: string, namespace: string ) : boolean,
// gets the value of an entry / namespace combination only if and when bifrost initialisation has completed
getAsync ( entry: string, namespace: string, cb: Function(value: any) ) : boolean
}
Store Reserved Keys
The Bifrost store has provision for reserved keys that are not persisted. Given a store instance store
, store.constructor.RESERVED_KEY
is an object mapping reserved keys and their namespaces to custom functions. Such keys have their custom function executed upon store.get
. Currently, the reserved key in-app
in the namespace browser
exists. store.get('in-app', 'browser')
returns Boolean true
iff Bifrost runs inside a Webhub-hosted web page that is configured to be executed in a in-app-browser web view.