Skip to main content

JavaScript Single-Page Application SDK

Overview​

A common problem for SPA front-ends is to conditionally display UI elements based on the set of permissions that the logged-in user possesses. For example, if a user only has "viewer" permissions, the front-end typically wants to avoid displaying UI elements that allow users to edit or update resources.

We address this problem by defining the display state map pattern.

The Aserto JavaScript SPA SDK works together with other high-level language SDKs like the Node.js to allow retrieving this display state map when the user logs in (and/or reload it). This in turn can be used to instruct the UI on whether to render specific UI elements that correspond to these routes / permissions.

Credits​

Loosely modeled after the Auth0 SPA SDK.

GitHub​

This SDK is open source and can be found on GitHub.

Installation​

Using npm:

npm install @aserto/aserto-spa-js

Using yarn:

yarn add @aserto/aserto-spa-js

Getting Started​

Creating the client​

Create an AsertoClient instance before rendering or initializing your application. You should only have one instance of the client.

You need a valid access token before you can instantiate the client. For the next few examples, the accessToken variable is assumed to contain a valid access token.

To obtain one via Auth0 (for example), use code like this:

// get a valid access token, e.g. from Auth0 getTokenSilently()
import createAuth0Client from '@auth0/auth0-spa-js';
const auth0 = await createAuth0Cient(
  domain: '<AUTH0_DOMAIN>',
  client_id: '<AUTH0_CLIENT_ID>',
  redirect_uri: '<MY_CALLBACK_URL>'
);
const accessToken = await auth0.getTokenSilently();

Create an AsertoClient in the following way:

import createAsertoClient from '@aserto/aserto-spa-js'

const aserto = await createAsertoClient({
  accessToken: accessToken, // valid access token
  serviceUrl: 'https://service-url', // defaults to window.location.origin
  endpoint: '/__displaystatemap', // access map endpoint, defaults to /__displaystatemap
})

// or you can just instantiate the client on its own
import { AsertoClient } from '@aserto/aserto-spa-js'

const aserto = new AsertoClient({
  accessToken: accessToken,
  serviceUrl: 'https://service-url', // defaults to window.location.origin
  endpoint: '/__displaystatemap', // access map endpoint, defaults to  /__displaystatemap
})

// explicitly load
await aserto.reload()

Usage​

displayStateMap()​

Retrieves a javascript object that holds the display state map

console.log(aserto.displayStateMap())

getDisplayState('method, 'path')​

Retrieves the display state associated with a specific resource.

By convention, the method argument is an HTTP method (GET, POST, PUT, DELETE), and the path argument is in the form /path/to/resource. It may contain a __id component to indicate an parameter - for example, /mycars/__id.

If only the method argument is passed in, it is assumed to be a key into the displayStateMap (typically in the form of METHOD/path/to/resource).

The returned map will be in the following format:

{
  visible: true,
  enabled: false,
}

Check whether a verb / path combination is visible and enabled:

const method = 'GET';
const path = '/api/path';
const displayState = aserto.getDisplayState(method, path));
const isVisible = displayState.visible;
const isEnabled = displayState.enabled;

Log the display state values for each verb for the path:

const path = '/api/path';
for (const verb of ['GET', 'POST', 'PUT', 'DELETE']) {
  const resource = aserto.getDisplayState(verb, path));
  for (const value of ['visible', 'enabled']) {
    console.log(`${verb} ${path} ${value} is ${resource[verb][value]}`);
  }
}