Building an app for Livestax

Overview

Livestax allows you to quickly and easily build secure web views on top of your data held in your IT systems. We call these web views apps.

At a high level, you host one or more applications that serve an HTML page at a URL. This URL is added as an app to Livestax. When your users visit Livestax and add your app, their browser loads your app, alongside others, inside iframes in the user's browser.

This is just the beginning though, because the platform provides:

authentication and authorisation for users
a JavaScript messaging API which allows apps to communicate with each other
a JavaScript key-value store API for storing state and sharing it with other apps
a theme and component library so that you can quickly and easily build a great looking, consistent experience that works across browsers, without requiring specialist frontend skills
much much more

Adding your app to Livestax

To add an app to an organisation in Livestax, there are a few pieces of information that are required:

Name of the app
App URL - the URL for loading your app
Namespace - this is a unique identifier for your app used in the messaging and key-value store APIs
Whether the app is loaded over GET or POST (see Authentication)

When you add an app, we generate a secret key for it. This secret key is needed if you are using the POST loading method and/or the user API

Minimum requirements for an app

The most basic Livestax app would be an HTML page which loads the Livestax JS API.

You'll need to host the HTML somewhere that your users can access it over HTTPS - either on the public internet or within a corporate network.

If you want to use the Livestax authentication and authorisation system, your app has to be loaded by HTTP POST, which will require some server-side code.

Livestax apps are webpages, so you'll need to know some HTML and JavaScript. The server-side code can be written in any language - you are free to choose the one you'll be most productive in.

HTTPS

For security reasons, all apps must be loaded over HTTPS. This includes any assets (images, JavaScript, CSS, webfonts) that your app fetches and any forms that your app includes. This is necessary because web browsers block non-HTTPS assets on HTTP pages - this is called Mixed Content.

To serve your app over HTTPS, the server hosting your app needs an HTTPS certificate. There are many different vendors who can sell you HTTPS certificates (you might have them already), but you might like to look at Let's Encrypt as a zero-cost option.

To enable HTTPS for local development only, one option is using a self-signed root certificate. Please note that this isn't suitable for production environments. Here is a walk-through for a self-signed root certificate using openssl.

Authentication

Livestax has internal access controls to prevent users accessing data and apps that they shouldn't. To use Livestax's built-in authentication, your app must be loaded using HTTP POST.

When Livestax loads your app via POST, it includes a JSON Web Token (JWT) in the request body. This token is cryptographically signed using a secret that is specific to your app. When your application receives the POST request from the user's browser containing the token, this tells you:

this user is signed into an active Livestax account
this user has been granted access to your app in Livestax
this user's Livestax user UUID, which you can use to fetch their details from the User API
this data was generated by Livestax within the last 30 minutes - because it is signed using your app's secret key and the token expires after 30 minutes

App loading and authentication flow

Diagram showing the initial app load and authentication flow

Note: this diagram shows the POST loading method. The GET method works similarly, but for security reasons the signed request is not supplied and your app doesn't connect to the Livestax User API.

GET or POST?

Livestax supports two ways of loading your app: with an HTTP GET or POST.

The POST loading method is suitable when:

You want to rely on Livestax to handle authentication and authorisation

The GET loading method is suitable when:

You don't need authentication - you might be displaying a public Twitter or RSS feed
You want to do your own authentication, for example by asking the user to login directly or with OAuth for example. Read more about support for OAuth
Access to the app is already controlled because it is only available in your corporate network or VPN
You want your app to be client-side only, rather than requiring server side code to handle the POST request

Additional authentication options

Livestax has a great authentication system built-in to let your app rely on Livestax for user management, authentication and authorisation. The great thing about the flexible architecture is that you are free to use existing authentication systems instead, or to mix and match to get the best of both worlds.

Your application's own sign in process. This can make it easier to integrate legacy apps without writing new code.
OAuth integration with third parties or your own OAuth system. Livestax provides a smooth user experience for using OAuth so that your apps can integrate with third party services, such as Google, Salesforce, Twitter, GitHub and thousands more.
IP/Firewall based access control - restrict access to within your corporate IP ranges
VPN security

JavaScript API

Our JavaScript API provides essential functionality to integrate your app with Livestax itself and so that it can communicate with other apps in the user's browser, without requiring you to implement any kind of push messaging system. It also includes various API calls for user interaction.

Theme and component library

Livestax provides a theme to enable you to quickly create consistent apps without needing years of frontend experience.

The Livestax Developer Hub