CustomAuth Web SDKs (Previously DirectAuth)
Web3Multifactor is where passwordless auth meets non-custodial key infrastructure for Web3 apps and wallets. By aggregating OAuth (Google, Twitter, Discord) logins, different wallets and innovative Multi Party Computation (MPC) - Web3Auth provides a seamless login experience to every user on your application.
Introduction
This repo allows web applications to directly retrieve keys stored on the Multifactors Network. The attestation layer for the Multifactors Network is generalizable, below is an example of how to access keys via the SDK via Google.
Features
- Typescript compatible. Includes Type definitions
- All API's return
Promises
Installation
Bundling
This module is distributed in 4 formats
-
esm
builddist/customauth.esm.js
in es6 format -
commonjs
builddist/customauth.cjs.js
in es5 format -
commonjs
builddist/customauth-bundled.cjs.js
in es5 format with problematic packages bundled (benfits non-webpack users) -
umd
builddist/customauth.umd.min.js
in es5 format without polyfilling corejs minified
By default, the appropriate format is used for your specified usecase You can use a different format (if you know what you're doing) by referencing the correct file
The cjs build is not polyfilled with core-js. It is upto the user to polyfill based on the browserlist they target
Directly in Browser
CDN's serve the non-core-js polyfilled version by default. You can use a different
jsdeliver
<script src="https://cdn.jsdelivr.net/npm/@oraichain/customauth@6"></script>
unpkg
<script src="https://unpkg.com/@oraichain/customauth@6"></script>
Notes
This is a plugin that works only on the client side. So please register it as a ssr-free plugin.
Usage
For more in-depth documentation, please refer to docs here
Add @oraichain/customauth
to your project:
To allow your web app to retrieve keys:
Install the package
npm i @oraichain/customauth
or
yarn add @oraichain/customauth
CustomAuth Sdk supports two modes of login (uxMode: "popup"
and uxMode: "redirect"
) (default: popup
)
Popup Flow:
-
Serve service worker from
baseUrl
where baseUrl is the one passed while instantiatingCustomAuth
for specific login (example http://localhost:3000/serviceworker/). If you're already using a sw, pls ensure to port over the fetch override from our service worker -
For browsers where service workers are not supported or if you wish to not use service workers, create and serve redirect page from
baseUrl/redirect
where baseUrl is the one passed while instantiatingCustomAuth
for specific login ( example http://localhost:3000/serviceworker/) -
At verifier's interface (where you obtain client id), please use
baseUrl/redirect
(eg: http://localhost:3000/serviceworker/redirect) as the redirect_uri where baseUrl is the one passed while instantiatingCustomAuth
-
Instantiate the package
const torus = new CustomAuth({
baseUrl: "http://localhost:3000/serviceworker/",
network: "testnet", // details for test net
});
await torus.init();
- Trigger the login with your own client id (This opens a popup of OAuth provider page)
const loginDetails = await torus.triggerLogin({
typeOfLogin: "google",
verifier: "YOUR VERIFER DEPLOYED BY TORUS",
clientId: "MY CLIENT ID GOOGLE",
});
Note: If you're using redirectToOpener
, modify the origin of postMessage from "http://localhost:3000"
to your hosted domain in redirect.html and sw.js
Redirect flow
-
At verifier's interface (where you obtain client id), please use
baseUrl/auth
(eg: http://localhost:3000/auth) as the redirect_uri where baseUrl is the one passed while instantiatingCustomAuth
-
Instantiate the package
const torus = new CustomAuth({
baseUrl: "http://localhost:3000/serviceworker/",
redirectPathName: "auth",
network: "testnet", // details for test net
uxMode: "redirect",
});
await torus.init({ skipSw: true });
- Trigger the login with your client id. (This redirects the user to OAuth provider page)
await torus.triggerLogin({
typeOfLogin: "google",
verifier: "YOUR VERIFER DEPLOYED BY TORUS",
clientId: "MY CLIENT ID GOOGLE",
});
- The OAuth login completes and the OAuth provider will redirect you to
baseUrl/auth
with hashParams In this page, use the following code to get the login details
const torus = new CustomAuth({
baseUrl: location.origin,
redirectPathName: "auth",
uxMode: "redirect",
network: "testnet",
});
const loginDetails = await torus.getRedirectResult();
- Once you get the login details, you can choose to take the user anywhere else in your app
Best practices
- Due to browser restrictions on popups, you should reduce the time taken between user interaction and the login popups being opened. This is highly browser dependent, but the best practice for this is to separate the initialization of the SDK and the user login method calls.
FAQ
-
Question: My Redirect page is stuck in iOS Chrome
**Answer:**
iOS Chrome doesn't support service workers. So, you need to serve a fallback html page
redirect.html
Please check if redirect.html is being served correctly by navigating tobaseUrl/redirect#a=123
. It should show a loaderFor nginx, here is a simple server configuration ```nginx location ~* (/serviceworker/redirect) { add_header 'Access-Control-Allow-Origin' '*';