onz-auth-js

npm version Release

OnzAuth

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.

Quick Intro

Our SDK is a vanilla javascript Framework meant to work with any frontend languages. Framework specific support and documentations are coming soon.

The SDK doesn’t provide any server side logic for verifying or dealing with the JWT tokens. But there are tons of libraries available for your own particular languages and platforms, for example, https://github.com/golang-jwt/jwt for golang. Please look at Standard OAuth Endpoints for more information.


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.

Sample Code and Plugins Guides

ReactJS and NodeJS Demo

View the Guide

Please refer to demo repository. Repository for more information

Webflow Sample Guide

View the Webflow guide

WordPress Plugin Setup Guide

View the WordPress guide

Please refer to plugin repository “Releases” tab to download the zip file or download it directly from the Wordpress Plugins

Git Repository for the plugin


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');
});

How it works

OnzAuth


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'.
Note: iframe mode will not work with WebAuthN creation (registration), but registered (WebAuthN) users will be able to log in within an iframe. More info


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


Standard OAuth2 Public endpoints

Authentication Endpoint Description
https://auth.onzauth.com/.well-known/jwks.json JWK Key discovery. This endpoint returns JSON Web Keys to be used as public keys for verifying OpenID Connect ID Tokens and, if enabled, OAuth 2.0 JWT Access Tokens. This endpoint can be used with client libraries like node-jwks-rsa among others.
https://auth.onzauth.com/.well-known/openid-configuration The well known endpoint an be used to retrieve information for OpenID Connect clients. We encourage you to not roll your own OpenID Connect client but to use an OpenID Connect client library instead. You can learn more on this flow at https://openid.net/specs/openid-connect-discovery-1_0.html . Popular libraries for OpenID Connect clients include oidc-client-js (JavaScript), go-oidc (Golang), and others. For a full list of clients go here: https://openid.net/developers/certified/
https://auth.onzauth.com//oauth2/auth Authorisation URL
https://auth.onzauth.com//oauth2/token Token Url
https://auth.onzauth.com//oauth2/revoke https://auth.onzauth.com//oauth2/fallbacks/consent https://auth.onzauth.com//oauth2/fallbacks/error https://auth.onzauth.com//oauth2/sessions/logout https://auth.onzauth.com//userinfo Others
This site is open source. Improve this page.