ZeroAuth

Table of Contents

Quick Start

In this guide, we'll walk you through integrating zkLogin into your web application using the ZeroAuth Web SDK. Everything you need to kickstart the process is covered here, and the concepts are equally applicable to websites.

Prerequisites

This guide assumes you have a basic understanding of web development and JavaScript. It also assumes you have a conceptual understanding of zkLogin. If you are new to zkLogin, please refer to the zkLogin documentationopen in new window.

If you understand the above, you are ready to get started, but before we do, you must have the following:

  • OAuth client credentials (clientId) from an OAuth provider. For this guide, we will use Google, but the process is similar for other providers. You typically get this from the OAuth provider's developer console.
  • A remote salting service. For this guide, we will use the default remote salting service provided by Mysten Labsopen in new window, but the process is similar for other remote salting services including standard self-hosted salting services. For this, your client credentials must be whitelisted by Mysten Labsopen in new window.
  • A remote proving service. For this guide, we will use the default remote proving service provided by Mysten Labsopen in new window, but the process is similar for other remote proving services including standard self-hosted proving services. For this, your client credentials must be whitelisted by Mysten Labsopen in new window.

Installation

WARNING

ZeroAuth zkLogin Web SDK is currently in beta stage, and the API is subject to rapid changes until the first stable release. Please report any issues you encounter. Currently only snapshot versions are available. Stable versions will be available soon.

To add ZeroAuth SDK to a web project depends on how you are building your project. For example, if you are using a bundler like Webpack or Vite, you can install the SDK using npm or yarn or pnpm:

pnpm add @mcxross/zero

npm install @mcxross/zero

yarn add @mcxross/zero

If you are using a CDN, you can add the following to your HTML file:

<script src="https://unpkg.com/@mcxross/zero@<version>"></script>

TIP

The ZeroAuth Web SDK offers two library flavors to cater for different development needs:

  • Release Flavor: This flavor is optimized for production environments.
  • A Snapshot Flavor: This version is tailored for development and testing phases. It includes additional logging to aid developers in troubleshooting and refining the ZeroAuth integration within their projects. The snapshot flavor is only available via npm, yarn, or pnpm. It is not available via CDN.

Usage

The usage (the code) of the ZeroAuth Web SDK matches the conceptual overview described in the Conceptual Overview section.

ZKLoginRequest

Create an instance of the ZKLoginRequest object.

const provider = new zero.Google();
const cfg = new zero.OpenIDServiceConfiguration(
    provider,
    "YOUR_CLIENT_ID",
    "YOUR_REDIRECT_URI",
);
const zkLoginRequest = new zero.ZKLoginRequest(
    cfg,
);

const provider: zero.Google = new zero.Google();
const cfg: zero.OpenIDServiceConfiguration = new zero.OpenIDServiceConfiguration(
    provider,
    "YOUR_CLIENT_ID",
    "YOUR_REDIRECT_URI"
);
const zkLoginRequest: zero.ZKLoginRequest = new zero.ZKLoginRequest(
    cfg
);

val zkLoginRequest = ZKLoginRequest(OpenIDServiceConfiguration(Google(), clientID = "YOUR_CLIENT_ID", redirectUri = "YOUR_REDIRECT_URI"))

Trigger zkLogin flow

Pass the zkLogin request object to the zkLogin callable:

zero.zkLogin(zkLoginRequest);

zero.zkLogin(zkLoginRequest);

zkLogin(zkLoginRequest)

This will trigger a redirect to the OAuth provider's login page. Once the user has successfully logged in, the OAuth provider redirects the user back to the redirect_uri you specified in the zkLogin request object.

Handle the redirect

Okay, now we need to handle the redirect. To do this, we need to use a special continueWithZKLogin function on the redirect_uri page. This takes in a Salting Service, a Proving Service, and a ZKLoginNotifier. If the first two are not provided, the default remote salting and proving services provided by Mysten Labsopen in new window will be attempted.

const zkLoginNotifier = new zero.ZKLoginNotifier();
const listener = {
    invoke: function(request, response, error) {
        // Do something with the response
    }
};
zkLoginNotifier.setListener(listener);
zero.continueWithZKLogin(null, null, zkLoginNotifier);

const zkLoginNotifier: zero.ZKLoginNotifier = new zero.ZKLoginNotifier();
const listener: zero.Listener = {
    invoke: function(request: zero.Request, response: zero.Response, error: zero.Error): void {
        // Do something with the response
    }
};
zkLoginNotifier.setListener(listener);
zero.continueWithZKLogin(null, null, zkLoginNotifier);

To be added

The notifier will deliver the results of the process to your provided listener, which you can use to handle the results

Last Updated: