onz-auth

OnzAuth JavaScript SDK

OnzAuth's JS SDK for Passwordless Authentication using Email Magic Link and WebAuthN.

Implement Authentication in 5 mins or less, straightforward support for magic link or WebAuthN, no passwords to manage, no callbacks to implement.

Questions?

Join our Slack Community

Demo

View the Demo Application

Please refer to demo/index.htm for demo code

Note: WebAuthN registration is seemless, so login users will only need to confirm their emails the very first time only when they register with WebAuthN, but will have a more seamless experience the second time onwards.

Install

npm install onz-auth --save

or

<script src="https://unpkg.com/onz-auth@1.0.26/dist/onz-auth-js-sdk.min.js"></script>

Quickstart

You'll need a CLIENT_ID, which you can get by creating a free account at OnzAuth.

WebAuthN can be enabled in the settings options after project creation. It is disabled by default.

import onz from "onz-auth"; // If using npm or included in script import

// Initialisation
const auth = new onz.Auth({
    clientID: 'Your Client ID', // Options
    containerID: 'myDiv', // Optional, defaults to 'container'
    isIframe: true, // Optional, defaults to 'false'
});

Sign in

Tokens will automatically be saved in localstorage with the following keys access_token, id_token, expiry, refresh_token after successful signin

auth.showLogin(); // Shows the login popup

Sign out

Tokens will automatically be cleared from localstorage after signing out

auth.logout(); // Signs out the current user

Events examples

// Authenticated event, after log in successful, contains accessToken, idToken, refreshToken, expiry
auth.on("authenticated", (authResult) => {
    console.log('authentication result', authResult);
    console.log('authentication access token', authResult.accessToken);
});

// Error message
auth.on("error", (errorMessage) => {
    console.error('authentication error', errorMessage);
});

// On popup or iframe closed
auth.on("closed", () => {
    console.log('iframe or popup is closed');
});

Options

Parameter Name	Type	Required	Description
clientID	string	Yes	Generated ClientID in OnzAuth
containerID	string	Optional	The element container id for the iframe or popup to attach to, will default to 'container'
isIframe	boolean	Optional	Value indicating whether it is a popup or an iframe, defaults to 'false'

Methods

Method	Return Type	Description
showLogin()	nil	Shows the login popup or iframe to initiate a new Log in flow
updateOptions(options)	nil	Updates the existing options when initialised Options Object { clientID: 'Your Client ID', // Optional containerID: 'myDiv', // Optional isIframe: true, // Optional }
isLoggingIn()	boolean	Returns whether a login flow is in progress
close()	nil	Closes the popup or iframe at any time, will invoke the closed event if one is opened or active
refreshAccessToken(refreshToken: optional)	nil	Initiate refresh token call, will invoke refreshed event when succeeded. Parameter is optional, will default to localstorage token
logout(idToken: optional)	nil	Signs out the user, will be using a hidden iframe, so when it finishes, close event will be invoked together with logged_out. Parameter is optional, will default to localstorage token
isAuthenticated(accessToken: optional)	boolean	Checks if the current token is valid. Parameter is optional, will default to localstorage token
getOAuthTokens()	object	Gets authResult object from localstorage it exists
getAccessToken()	string	Gets access token from localstorage if it exists
getDecodedAccessToken()	object	Gets access token jwt object from localstorage if it exists
getIDToken()	string	Gets id token from localstorage if it exists
getDecodedIDToken()	object	Gets id token jwt object from localstorage if it exists
getRefreshToken()	string	Gets refresh token from localstorage if it exists

Events

Event Name	Description	Type	Param
authenticated	On login success	object	{ accessToken, refreshToken, idToken, expiry }
refreshed	When token is refreshed	object	{ accessToken, refreshToken, idToken, expiry }
error	When an exception occurred	string	errorMessage
closed	When popup or iframe is closed	nil	nil
logged_out	When session is cleared and logged out	nil	nil