@cimpress/simple-auth-wrapper

MEX Simple Auth Wrapper v. 3.0

About

This is a lightweight wrapper for Auth0, removing the need to write and re-write many standard utility functions.

Check out the Changelog to see the latest changes.

Using

To see an example of implementing this wrapper using centralized login with a Cimpress client see Single Page Application Sample

For migrating from embedded auth to centralized auth see Embedded to Centralized Migration

Client Configuration

Using Cimpress Client Configuration, create a Single Page App client configuration. This clientId will be used to configure the wrapper. Add Allowed Callback URLs, Allowed Logout URLs, and Allowed Web Origins corresponding to your application.

Import the library and instantiate a new auth helper, passing in the domain, audience, your client ID, and a redirectUri for Auth0 to redirect to (in Auth0 v7 it's called callback url) after authentication. You need to pass in the relative route. For example, "/login". If domain and audience are left blank, domain will default to cimpress.auth0.com0 and audience will default to https://api.cimpress.io/. You probably will not need to manually set these.

npm install @cimpress/simple-auth-wrapper

import { centralizedAuth } from '@cimpress/simple-auth-wrapper';

const auth = new centralizedAuth(options); // see full list of supported options in centralizedauth.js

Then, the following are available to you:

ensureAuthentication(options) combines handleAuthentication and login together. This single call can be used on page load and it will do everything necessary to ensure the user is authenticated. This method accepts the same options object as the login(options) method below.

handleAuthentication() parses the hash that is on the url on return from authentication. This function will automatically redirect you to the url passed into login. Returns a promise that resolves to a boolean of the authentication status.

login(options) Logs a user in with Auth0: first check if an SSO session exists and if so log in with it, if not, redirect to the centralized login page. Returns a promise that resolves to a boolean of the authentication status. Listed below are the available options you can use with this method.

Name	Type	Default	Description
nextUri	String	"/"	If the user cannot be granted a new token via Single Sign On, then they will be taken through the whole webAuth.authorize() flow and will be taken back to this nextUri route.
forceLogin	Boolean	false	If true, the user's auth information will be removed from localStorage forcing them to go through the whole webAuth.authorize() flow (as opposed to getting a new token via Single Sign On).

logout(nextUrl, logoutOfFederated) Logs a user out and removes their token and profile from local storage. Will open URL provided in nextURL. If the optional logoutOfFederated is provided and is true, will also log user out from the identity provider. Note: this is not a common use case and most apps will not need to provide this parameter. For more information reference https://auth0.com/docs/logout

Subscribing to Events

Listed below are the different events you can subscribe to.

Name

Description

tokenExpired

This event is triggered when the user's token expires. If the user's token in localStorage is expired at the time this event is subscribed to (i.e. auth.on('tokenExpired', ...)) this event will immediately emit. You can turn this behavior off via the emitInitialTokenExpired constructor option. By default this event will emit 30 seconds before the actual expiry. You can change this offset value via the expirationOffset constructor option.

import { centralizedAuth } from '@cimpress/simple-auth-wrapper';

const auth = new centralizedAuth(options);

auth.on('tokenExpired', () => {
  // This is invoked each time the current token in localStorage becomes expired.
  // This will also be immediately invoked if the token in localStorage is already expired. (configurable via emitInitialTokenExpired)
  console.log('The token in local storage is expired.');
});

Delegation

Delegation is no longer part of the core wrapper. If you have a need for it, you can load it and optionally patch it to the auth object:

import { centralizedAuth, Delegation } from '@cimpress/simple-auth-wrapper';

const auth = new centralizedAuth(options);

const delegationHandler = new Delegation(auth);

auth.buildDelegationHeader = delegationHandler.buildDelegationHeader;

This will give you access to:

buildDelegationHeader(targetClientId) Build some fetch headers, getting the delegation token if needed. Note: delegation is deprecated and not recommended. We recommend using access token instead.

getDelegationToken(targetClientId) get a delegation token for the given target clientid. Note: delegation is deprecated and not recommended. We recommend using access token instead.

User metadata

User metadata is a place to store application settings for the users

import { UserMetadata } from '@cimpress/simple-auth-wrapper';
const auth; // your instantiated auth Wrapper

const userMetadata = new UserMetadata(auth);

userMetadata will then give you access to:

getUserMetadata(applicationKey) applicationKey is optional (defaults to app clientId). Gets a JSON object of all the applications UserMetadata

patchUserMetadata(userMetadata, applicationKey) applicationKey should match what is used for get. Puts the metadata into the users UserMetadata