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.
Aserto addresses 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]}`);
}
}