Usage of Core Kit SFA Web SDK
Once you've installed and successfully initialized Web3Auth, you can use it to authenticate your users. Further, you can use the native provider given by Web3Auth to connect the users to the respective blockchain network.
Natively, the instance of Web3Auth (called web3auth in our examples) returns the following functions:
connect()
- Logs in the User using theverifier
,verifierId
&idToken
, which are mandatory, whilesubVerifierInfoArray
andserverTimeOffset
are optional.provider()
- Returns the native provider that can be used to make different blockchain transactions.sessionId()
- Returns the sessionId of the user as a string.authenticateUser()
- Returns a promise of theUserAuthInfo
object containing theidToken
of the user.addChain()
- Add chain configuration to the web3auth instance.switchChain()
- Switches the chainId to one of the added chainIds.getUserInfo()
- Returns the user information.logout()
- Log out the user from the web3auth instance.
Logging in your User
connect(loginParams: LoginParams)
To log a user in the Web3Auth SFA Web SDK, you need to call the connect()
function.
Variable | Description |
---|---|
loginParams | Mandatory login Parameters |
Returns
connect(loginParams: LoginParams): Promise<IProvider | null>
LoginParams
connect(loginParams: LoginParams)
On successful login, the connect()
function returns a IProvider
instance. This instance contains
the corresponding provider for your selected blockchain. You can use this provider to connect your
user to the blockchain and perform transactions.
On unsuccessful login, this function will return a null
value.
LoginParams
- Table
- Type Declarations
Parameter | Description |
---|---|
verifier | Details of the verifier (verifier type, ie. torus , metamask , openlogin etc.). It's a mandatory parameter as a string. |
verifierId | Verifier ID's value, sub or email value present in the idToken. It's a mandatory parameter as a string. |
idToken | A newly created JWT Token that has not already been sent to Web3Auth or a Duplicate Token error will be thrown. It's a mandatory parameter as a string. |
subVerifierInfoArray? | Sub verifier info. It's an optional parameter as a TorusSubVerifierInfo[]. |
serverTimeOffset? | Server time offset. It's an optional parameter as a number. |
export type LoginParams = {
verifier: string;
verifierId: string;
idToken: string;
subVerifierInfoArray?: TorusSubVerifierInfo[];
serverTimeOffset?: number;
};
TorusSubVerifierInfo
- Table
- Interface
Parameter | Description |
---|---|
verifier | Details of the verifier (verifier type, ie. torus , metamask , openlogin etc.). It's a string mandatory parameter. |
idToken | A newly created JWT Token that has not already been sent to Web3Auth or a Duplicate Token error will be thrown. It's a string mandatory parameter. |
export interface TorusSubVerifierInfo {
verifier: string;
idToken: string;
}
Usage
await web3auth.connect({
verifier: "verifier-name", // e.g. `web3auth-sfa-verifier` replace with your verifier name, and it has to be on the same network passed in init().
verifierId: "verifier-id-value", // e.g. `Yux1873xnibdui` or `name@email.com` replace with your verifier id(sub or email)'s value.
idToken: "JWT Token", // replace with your newly created unused JWT Token.
});
Get a native provider
provider()
Returns the native provider that can be used to make different blockchain transactions.
Returns
get provider(): IProvider | null;
Get sessionId
sessionId()
Returns the sessionId of the user as a string.
Returns
get sessionId(): string;
Authenticate the user
authenticateUser()
Returns a promise of the UserAuthInfo
object containing the idToken
of the user.
Returns
authenticateUser(): Promise<UserAuthInfo>;
UserAuthInfo
export type UserAuthInfo = {
idToken: string;
};
Add a new chain
addChain(chainConfig: CustomChainConfig)
Add chain configuration to the web3auth instance.
Variable | Description |
---|---|
chainConfig | Mandatory chain-specific configuration as a CustomChainConfig type. |
CustomChainConfig
- Table
- Type Declarations
Parameter | Description |
---|---|
chainNamespace | Namespace of the chain. It's a mandatory parameter as a ChainNamespaceType type. |
chainId | The chain id of the chain. It's a mandatory parameter as a string . |
rpcTarget | RPC target URL for the chain. It's a mandatory parameter as a string . |
wsTarget | Web socket target URL for the chain. It's an optional parameter as a string . |
displayName | Display Name for the chain. It's an optional parameter as a string . |
blockExplorerUrl | URL of the block explorer. It's an optional parameter as a string . |
ticker | Default currency ticker of the network (e.g: ETH). It's an optional parameter as a string . |
tickerName | Name for currency ticker (e.g: Ethereum ). It's an optional parameter as a string . |
decimals | Number of decimals for the currency ticker (e.g: 18). It's an optional parameter as a number . |
logo | Logo for the token. It's an optional parameter as a string . |
isTestnet | Whether the network is testnet or not. It's an optional parameter as a boolean . |
export declare const ADAPTER_NAMESPACES: {
readonly EIP155: "eip155";
readonly SOLANA: "solana";
readonly CASPER: "casper";
readonly XRPL: "xrpl";
readonly MULTICHAIN: "multichain";
};
declare type ChainNamespaceType = (typeof CHAIN_NAMESPACES)[keyof typeof CHAIN_NAMESPACES];
export type CustomChainConfig = {
chainNamespace: ChainNamespaceType;
/**
* The chain id of the chain
*/
chainId: string;
/**
* RPC target Url for the chain
*/
rpcTarget: string;
/**
* web socket target Url for the chain
*/
wsTarget?: string;
/**
* Display Name for the chain
*/
displayName?: string;
/**
* Url of the block explorer
*/
blockExplorerUrl?: string;
/**
* Default currency ticker of the network (e.g: ETH)
*/
ticker?: string;
/**
* Name for currency ticker (e.g: `Ethereum`)
*/
tickerName?: string;
/**
* Number of decimals for the currency ticker (e.g: 18)
*/
decimals?: number;
/**
* Logo for the token
*/
logo?: string;
/**
* Whether the network is testnet or not
*/
isTestnet?: boolean;
};
Switch the chain
switchChain(params: {chainId: string;})
Switch to one of the added chains
Variable | Description |
---|---|
chainId | Id of the chain to switch to. It's a mandatory parameter as a string |
Logging out the user
logout()
Logs out the user and clears the session.
@web3auth/single-factor-auth
SDK only works for users who have not enabled MFA.
For MFA enabled users, you'll see
Error("User has already enabled mfa, please use the @webauth/webauth-web sdk for login with mfa");
Example
Custom JWT Example
import Web3Auth from "@web3auth/single-factor-auth";
import { EthereumPrivateKeyProvider } from "@web3auth/ethereum-provider";
import { CHAIN_NAMESPACES } from "@web3auth/base";
import jwt from "jsonwebtoken";
import fs from "fs";
// Use "openssl genrsa -out privateKey.pem 2048" to generate a private key
// Also, use this private key to generate a public key using "openssl rsa -in privateKey.pem -pubout -out publicKey.pem"
// Convert PEM to JWKS and expose it on a public URL, and make a web3auth verifier using that.
// Check out https://web3auth.io/docs/auth-provider-setup/byo-jwt-provider for more details.
var privateKey = fs.readFileSync("privateKey.pem");
// Define the chain config according to the chain you want to connect to
const chainConfig = {
chainNamespace: CHAIN_NAMESPACES.EIP155,
chainId: "0x1",
rpcTarget: "https://rpc.ankr.com/eth",
displayName: "Ethereum Mainnet",
blockExplorerUrl: "https://etherscan.io",
ticker: "ETH",
tickerName: "Ethereum",
};
// Instantiate Web3Auth SFA SDK
const web3authSfa = new Web3Auth({
clientId: "WEB3AUTH_CLIENT_ID", // Get your Client ID from the Web3Auth Dashboard
web3AuthNetwork: "sapphire_mainnet", // Replace with your network name
usePnPKey: false, // Setting this to true returns the same key as PnP Web SDK, By default, this SDK returns CoreKitKey.
});
// Instantiate Ethereum Provider
const privateKeyProvider = new EthereumPrivateKeyProvider({ config: { chainConfig } });
// Initialize Web3Auth SFA SDK
web3authSfa.init(privateKeyProvider);
const user = {
id: "faj2720i2fdG7NsqznOKrthDvq43", // must be unique to each user
name: "Mohammad Shahbaz Alam",
email: "shahbaz@web3auth.io",
profileImage: "https://avatars.githubusercontent.com/u/46641595?v=4",
};
// Login the user
const web3authSfaprovider = await web3auth.connect({
verifier: "web3auth-sfa-verifier", // e.g. `web3auth-sfa-verifier` replace with your verifier name, and it has to be on the same network passed in init().
verifierId: user.id, // e.g. `Yux1873xnibdui` or `name@email.com` replace with your verifier id(sub or email)'s value.
idToken: jwt.sign(
{
sub: user.id, // must be unique to each user
name: user.name,
email: user.email,
picture: user.profileImage,
aud: "urn:my-resource-server", // -> to be used in Custom Authentication as JWT Field
iss: "https://my-authz-server", // -> to be used in Custom Authentication as JWT Field
iat: Math.floor(Date.now() / 1000),
exp: Math.floor(Date.now() / 1000) + 60 * 60,
},
privateKey, // <-- privateKey to sign the JWT Token
{ algorithm: "RS256", keyid: "1bb9605c36e69386830202b2d" },
), // or replace it with your newly created unused JWT Token.
});
// Get the private key, The private key returned here is the CoreKit Key, since the usePnPKey is set to false.
const ethPrivateKey = await web3authSfaprovider.request({ method: "eth_private_key" });
console.log("ETH Private Key", ethPrivateKey);
Firebase JWT Example
import Web3Auth from "@web3auth/single-factor-auth";
import { EthereumPrivateKeyProvider } from "@web3auth/ethereum-provider";
import { CHAIN_NAMESPACES } from "@web3auth/base";
import { GoogleAuthProvider, getAuth, signInWithPopup, UserCredential } from "firebase/auth";
// Define the chain config according to the chain you want to connect to
const chainConfig = {
chainNamespace: CHAIN_NAMESPACES.EIP155,
chainId: "0x1",
rpcTarget: "https://rpc.ankr.com/eth",
displayName: "Ethereum Mainnet",
blockExplorerUrl: "https://etherscan.io",
ticker: "ETH",
tickerName: "Ethereum",
};
// Your web app's Firebase configuration
const firebaseConfig = {
apiKey: "AIzaSyB0nd9YsPLu-tpdCrsXn8wgsWVAiYEpQ_E",
authDomain: "web3auth-oauth-logins.firebaseapp.com",
projectId: "web3auth-oauth-logins",
storageBucket: "web3auth-oauth-logins.appspot.com",
messagingSenderId: "461819774167",
appId: "1:461819774167:web:e74addfb6cc88f3b5b9c92",
};
// Instantiate Web3Auth SFA SDK
const web3authSfa = new Web3Auth({
clientId: "WEB3AUTH_CLIENT_ID", // Get your Client ID from the Web3Auth Dashboard
web3AuthNetwork: "sapphire_mainnet", // Replace with your network name
usePnPKey: false, // Setting this to true returns the same key as PnP Web SDK, By default, this SDK returns CoreKitKey.
});
// Instantiate Ethereum Provider
const privateKeyProvider = new EthereumPrivateKeyProvider({ config: { chainConfig } });
// Initialize Web3Auth SFA SDK
web3authSfa.init(privateKeyProvider);
// Initialize Firebase and get idToken from Firebase
const app = initializeApp(firebaseConfig);
const auth = getAuth(app);
const googleProvider = new GoogleAuthProvider();
const res = await signInWithPopup(auth, googleProvider);
const idToken = await res.user.getIdToken(true);
// get sub value from firebase id token
const { sub } = parseToken(token); // parseToken is a function that parses the token and returns the payload.
// Login the user
const web3authSfaprovider = await web3auth.connect({
verifier: "web3auth-sfa-verifier", // e.g. `web3auth-sfa-verifier` replace with your verifier name, and it has to be on the same network passed in init().
verifierId: sub, // e.g. `Yux1873xnibdui` or `name@email.com` replace with your verifier id(sub or email)'s value.
idToken: idToken, // or replace it with your newly created unused JWT Token.
});
// Get the private key, The private key returned here is the CoreKit Key, since the usePnPKey is set to false.
const ethPrivateKey = await web3authSfaprovider.request({ method: "eth_private_key" });
console.log("ETH Private Key", ethPrivateKey);