Skip to main content

Passkeys Plugin for SFA Web SDK

@web3auth/passkeys-sfa-plugin​

The Passkeys SFA Plugin allows your application to use passkeys for secure and easy authentication. This plugin integrates seamlessly with Web3Auth Single Factor Auth (SFA) Web SDK, enabling passkey registration, login, and management functionalities.

Note

Passkeys SFA Plugin is designed for Web3Auth Single Factor Auth (SFA) Web SDK.

Installation​

npm install --save @web3auth/passkeys-sfa-plugin

Initialization​

Import the PasskeysPlugin class from @web3auth/passkeys-sfa-plugin.

import { PasskeysPlugin } from "@web3auth/passkeys-sfa-plugin";

Assign the PasskeysPlugin class to a variable​

After creating your Web3Auth SFA instance, you need to initialize the Passkeys Plugin and add it to the class for further usage.

const passkeysPlugin = new PasskeysPlugin(options);

This constructor takes an object with IPasskeysPluginOptions as input.

Arguments​

While initializing the Passkeys plugin, you need to pass the following parameters to the constructor:

ParameterDescription
rpID?Stands for relying party ID. Your app domain. If your app is hosted on "your.app.xyz", the RPID can be "your.app.xyz".
rpName?Stands for relying party name. Name of your app. We recommend setting it to the correctly capitalized name of your app.
buildEnv?Specifies the build environment to use: production, staging, testing, or development.

Add the passkeysPlugin class to your Web3Auth SFA instance​

After initializing the passkeysPlugin, use the addPlugin() function to add it to your Web3Auth SFA instance.

web3AuthInstance.addPlugin(passkeysPlugin);

Example​

import { PasskeysPlugin } from "@web3auth/passkeys-sfa-plugin";

const passkeysPlugin = new PasskeysPlugin({
  rpID: "your.app.xyz",
  rpName: "Your App",
});

web3auth.addPlugin(passkeysPlugin); // Add the plugin to web3auth

// Register a new passkey
await passkeysPlugin.registerPasskey({ username: "user@example.com" });

// Login with an existing passkey
await passkeysPlugin.loginWithPasskey({ authenticatorId: "authenticator_id" });

// List all registered passkeys
const passkeys = await passkeysPlugin.listAllPasskeys();
console.log(passkeys);
Note

First, a user needs to log in the usual way, and then register a passkey. The next time, they can log in using a passkey.

Using Passkeys SFA Plugin​

registerPasskey()​

Registers a new passkey for the user.

Parameters​

ParameterDescription
authenticatorAttachment?Option to restrict the type of authenticators that can be registered.
username?The passkey in the user device will be saved with this name. Default is loginProvider|verifierId.

Example​

await passkeysPlugin.registerPasskey({
  username: "user@example.com",
  authenticatorAttachment: "platform",
});

loginWithPasskey()​

Logs in the user with an existing passkey.

Parameters​

ParameterDescription
authenticatorId?The ID of the authenticator to use for login.

Example​

await passkeysPlugin.loginWithPasskey({
  authenticatorId: "authenticator_id",
});

listAllPasskeys()​

Lists all registered passkeys for the user.

Example​

const passkeys = await passkeysPlugin.listAllPasskeys();
console.log(passkeys);

Using with Web3Auth SFA​

Note

Below are two files, App.tsx and utils.ts, demonstrating the implementation of the Passkeys SFA Plugin. The utils.ts file is kept non-opinionated and can be configured according to your requirements for your users. Also, note that the passkeys flow is only supported on browsers that support WebAuthn. You need to check for browser support before registering or logging in with a passkey.

import { CHAIN_NAMESPACES, WEB3AUTH_NETWORK, IProvider } from "@web3auth/base";
import Web3Auth from "@web3auth/single-factor-auth";
import { PasskeysPlugin } from "@web3auth/passkeys-sfa-plugin";
import { shouldSupportPasskey } from "./utils";

const clientId = "Your_Web3Auth_Client_ID";

const chainConfig = {
  chainId: "0x1", // Please use 0x1 for Mainnet
  rpcTarget: "https://rpc.ankr.com/eth",
  displayName: "Ethereum Mainnet",
  blockExplorerUrl: "https://etherscan.io/",
  ticker: "ETH",
  tickerName: "Ethereum",
  logo: "https://images.toruswallet.io/eth.svg",
};

const web3AuthOptions = {
  clientId,
  chainConfig: { ...chainConfig, chainNamespace: CHAIN_NAMESPACES.EIP155 },
  web3AuthNetwork: WEB3AUTH_NETWORK.MAINNET,
};

const web3auth = new Web3Auth(web3AuthOptions);

const passkeysPlugin = new PasskeysPlugin({
  rpID: "your.app.xyz",
  rpName: "Your App",
});

web3auth.addPlugin(passkeysPlugin); // Add the plugin to web3auth

await web3auth.init();

await web3auth.connect({
  verifier: "your_verifier_name", // Pass the verifier name created on the Web3Auth dashboard
  verifierId: "your_verifier_id", // Pass the verifierId received from the OAuth provider
  idToken: "id_token", // Pass the idToken received from the OAuth provider
});

const result = shouldSupportPasskey();

if (!result.isBrowserSupported) {
  console.log("Browser not supported");
} else {
  // Register a new passkey
  await passkeysPlugin.registerPasskey({ username: "user@example.com" });

  // Login with an existing passkey
  await passkeysPlugin.loginWithPasskey({ authenticatorId: "authenticator_id" });

  // List all registered passkeys
  const passkeys = await passkeysPlugin.listAllPasskeys();
  console.log(passkeys);
}