@cimpress/simple-auth-wrapper

MEX Simple Auth Wrapper v. 2.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.

Following instructions are for Centralized auth. This is the recommended use. For legacy issues see Embedded Auth

Using

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(nextUrl) 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.

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(nextUrl) 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.

logout() Logs a user out and removes their token and profile from local storage. Also logs them out from the identity provider.

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