Skip to content

Commit aa45c91

Browse files
shahbaz17shahbaz17
authored
Merge pull request #973 from Web3Auth/corekit/fixes
[MPC Core Kit] Revamp the docs
2 parents df076d2 + 5ff5fa0 commit aa45c91

File tree

11 files changed

+1336
-1017
lines changed

11 files changed

+1336
-1017
lines changed

‎docs/sdk/core-kit/mpc-core-kit/authentication.mdx‎

Lines changed: 0 additions & 567 deletions
This file was deleted.

‎docs/sdk/core-kit/mpc-core-kit/authentication/authentication.mdx‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
---
2+
title: "Web3Auth MPC Core Kit JS SDK - Authentication"
3+
4+
sidebar_label: "Overview"
5+
description: "Web3Auth MPC Core Kit JS SDK - Authentication | Documentation - Web3Auth"
6+
---
7+
8+
import TabItem from "@theme/TabItem";
9+
import Tabs from "@theme/Tabs";
10+
11+
There are two ways to login your users, depending on the type of authentication method you've
12+
chosen. If you are looking for an Authentication Flow in your application like
13+
[Single Page Application(SPA)](https://www.oauth.com/oauth2-servers/single-page-apps/) flow, you can
14+
use the `loginWithOAuth` method.
15+
16+
If you are looking to pass a JWT-based IdToken to the SDK from your application, like
17+
[Regular Web Application(RWA)](https://www.oauth.com/oauth2-servers/server-side-apps/) Flow or even
18+
using your own JWT provider, you can use the `loginWithJWT` method.
19+
20+
As a prerequisite, before triggering the login function, you need to create a verifier for your
21+
login method on the [Web3Auth Dashboard](https://dashboard.web3auth.io).
22+
23+
## Creating a Verifier
24+
25+
Since this is a Core Kit SDK, it does not provide any default authentication methods. You need to
26+
create a custom verifier to use this SDK. This means that you need to authenticate users with your
27+
own custom authentication service.
28+
29+
For example, while authenticating with Google, you have to use your own Google Client ID setup to
30+
authenticate users directly or use auth provider services like Auth0, Firebase, AWS Cognito etc.
31+
Additionally, you can make your own JWT token authentication system and pass over the ID Token to
32+
Web3Auth.
33+
34+
[Learn how to create a verifier](/auth-provider-setup/verifiers).
35+
36+
![Create a Verifier](/images/dashboard/create-verifier.gif)
37+
38+
## Login Methods
39+
40+
As discussed earlier, there are two login methods available in the SDK tailored to your use case.
41+
42+
- [Login with OAuth](/sdk/core-kit/mpc-core-kit/authentication/login-oauth): You can use this method
43+
the implicit login flow, where you don't need to manually handle the authentication and get the
44+
JWT token.
45+
46+
- [Login with JWT](/sdk/core-kit/mpc-core-kit/authentication/login-jwt): You can use this method to
47+
manually handle the authentication, and send the JWT token to Web3Auth. This method allows you to
48+
bring your own authentication flow.
49+
50+
:::tip Recommended
51+
52+
For faster login speeds, we recommend using the
53+
[Login with JWT](/sdk/core-kit/mpc-core-kit/authentication/login-jwt) method.
54+
55+
:::
56+
57+
## Backend verification
58+
59+
To verify the user in the backend, you can retrieve the user's signature from frontend, and validate
60+
it using the `SignatureValidator` from the
61+
[@toruslabs/signature-validator](https://www.npmjs.com/package/@toruslabs/signature-validator)
62+
package in the backend.
63+
64+
### Retrieve user's signature
65+
66+
To retrieve user's signature you can use the `signatures` getter from `Web3AuthMPCCoreKit`.
67+
68+
```tsx
69+
const signatures = coreKitInstance.signatures;
70+
71+
// Send these signatures to backend through an API
72+
```
73+
74+
### Verify the signatures in backend
75+
76+
For verification you'll need to install couple of packages,
77+
[@toruslabs/signature-validator](https://www.npmjs.com/package/@toruslabs/signature-validator) and
78+
[@toruslabs/fnd-base](https://www.npmjs.com/package/@toruslabs/fnd-base), and use
79+
`SignatureValidator` to validate the signatures.
80+
81+
```js
82+
const { fetchLocalConfig } = require("@toruslabs/fnd-base");
83+
const { SignatureValidator } = require("@toruslabs/signature-validator");
84+
85+
// Here network can be "sapphire_mainnet" or "sapphire_testnet", since MPC doesn't support
86+
// legacy networks.
87+
const network = "sapphire_mainnet";
88+
89+
// Fetch the node details
90+
const nodeDetails = fetchLocalConfig(network, "secp256k1");
91+
92+
const nodePubX = [];
93+
const nodePubY = [];
94+
95+
nodeDetails.torusNodePub.forEach((key) => {
96+
nodePubX.push(key.X);
97+
nodePubY.push(key.Y);
98+
});
99+
100+
// Create the SignatureValidator object
101+
const sigValidator = new SignatureValidator({
102+
nodePubKeyX: nodePubX.join(","),
103+
nodePubKeyY: nodePubY.join(","),
104+
});
105+
106+
// Get the signatures from the frontend & validate the signatures
107+
const result = sigValidator.authenticate(signatures, { skipExpValidation: false });
108+
109+
if (!result) {
110+
// Handle invalid singature
111+
}
112+
113+
// Handle the valid signature
114+
```

‎docs/sdk/core-kit/mpc-core-kit/authentication/login-jwt.mdx‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
---
2+
title: "Log in with JWT(BYOA)"
3+
4+
sidebar_label: "Log in with JWT(BYOA)"
5+
description: "Web3Auth MPC Core Kit JS SDK - Login with JWT(BYOA) | Documentation - Web3Auth"
6+
---
7+
8+
import Tabs from "@theme/Tabs";
9+
import TabItem from "@theme/TabItem";
10+
11+
To authenticate users using Regular Web Application(RWA) flow, you can use the `loginWithJWT`
12+
method. This methods takes the `JWTLoginParams` as a parameter, which is an object that contains the
13+
details of the verifier, and additional authentication parameters like idToken, subVerifier, etc.
14+
15+
In JWT login flow, you'll have to manually get the idToken from the auth provider and pass it to the
16+
login function.
17+
18+
## Parameters
19+
20+
<Tabs
21+
defaultValue="table"
22+
values={[
23+
{ label: "Table", value: "table" },
24+
{ label: "Type", value: "type" },
25+
]}
26+
>
27+
28+
<TabItem value="table">
29+
30+
| Parameter | Description |
31+
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
32+
| `verifier` | Name of the verifier created on Web3Auth Dashboard. In the case of Aggregate Verifier, the name of the top-level aggregate verifier. |
33+
| `verifierId` | Unique Identifier for the User. The verifier identifier field is set for the verifier/sub verifier. E.g. "sub" field in your JWT ID Token. |
34+
| `idToken` | The idToken received from the Auth Provider. |
35+
| `subVerifier?` | Name of the sub verifier in case of aggregate verifier setup. This field is mandatory in the case of an aggregate verifier. |
36+
| `extraVerifierParams?` | Extra verifier params in case of a WebAuthn verifier type. |
37+
| `additionalParams?` | Any additional parameter (key-value pair) you'd like to pass to the login function. |
38+
| `importTssKey?` | Key to import key into TSS during first time login. For secp256k1 curve, you need to pass the private key, and for ed25519 curve you need to pass the seed. The ed25519 seed is hashed to generate 64 bytes, where first 32 bytes are used to generate the public key, and last 32 bytes are used as private key. |
39+
| `prefetchTssPublicKeys?` | Number of TSS public keys to prefetch. |
40+
41+
</TabItem>
42+
<TabItem value="type">
43+
44+
```tsx
45+
interface JWTLoginParams {
46+
/**
47+
* Name of the verifier created on Web3Auth Dashboard. In case of Aggregate Verifier, the name of the top level aggregate verifier.
48+
*/
49+
verifier: string;
50+
/**
51+
* Unique Identifier for the User. The verifier identifier field set for the verifier/ sub verifier. E.g. "sub" field in your on jwt id token.
52+
*/
53+
verifierId: string;
54+
/**
55+
* The idToken received from the Auth Provider.
56+
*/
57+
idToken: string;
58+
/**
59+
* Name of the sub verifier in case of aggregate verifier setup. This field should only be provided in case of an aggregate verifier.
60+
*/
61+
subVerifier?: string;
62+
/**
63+
* Extra verifier params in case of a WebAuthn verifier type.
64+
*/
65+
extraVerifierParams?: PasskeyExtraParams;
66+
/**
67+
* Any additional parameter (key value pair) you'd like to pass to the login function.
68+
*/
69+
additionalParams?: ExtraParams;
70+
/**
71+
* Key to import key into Tss during first time login.
72+
*/
73+
importTssKey?: string;
74+
/**
75+
* Number of TSS public keys to prefetch. For the best performance, set it to
76+
* the number of factors you want to create. Set it to 0 for an existing user.
77+
* Default is 1, maximum is 3.
78+
*/
79+
prefetchTssPublicKeys?: number;
80+
}
81+
82+
export interface ExtraParams {
83+
[key: string]: unknown;
84+
}
85+
86+
export type WebAuthnExtraParams = {
87+
signature?: string;
88+
clientDataJSON?: string;
89+
authenticatorData?: string;
90+
publicKey?: string;
91+
challenge?: string;
92+
rpOrigin?: string;
93+
credId?: string;
94+
transports?: AuthenticatorTransport[];
95+
};
96+
97+
type AuthenticatorTransport = "ble" | "hybrid" | "internal" | "nfc" | "usb";
98+
```
99+
100+
</TabItem>
101+
102+
</Tabs>
103+
104+
## Usage
105+
106+
### Single Verifier
107+
108+
To login with a single verifier, you will require to create a custom verifier in the Web3Auth
109+
dashboard. If you haven't already created one,
110+
[learn how to create a verifier](/docs/auth-provider-setup/byo-jwt-provider/#set-up-custom-jwt-verifier).
111+
112+
```tsx
113+
import { JWTLoginParams } from "@web3auth/mpc-core-kit";
114+
115+
const jwtLoginParams: JWTLoginParams = {
116+
verifier: "YOUR_VERIFIER_NAME",
117+
verifierId: "USER'S_VERIFIER_ID",
118+
idToken: "USER'S_ID_TOKEN",
119+
};
120+
121+
await coreKitInstance.loginWithJWT(jwtLoginParams);
122+
```
123+
124+
### Aggregate Verifier
125+
126+
To login with an aggregate verifier, you will require to create an aggregate verifier in the
127+
Web3Auth dashboard. If you haven't already created one,
128+
[learn how to create an aggregate verifier](/docs/auth-provider-setup/aggregate-verifier#set-up-an-aggregate-verifier).
129+
130+
```tsx
131+
import { JWTLoginParams } from "@web3auth/mpc-core-kit";
132+
133+
const jwtLoginParams = {
134+
verifier: "YOUR_AGGREGATE_VERIFIER_NAME"
135+
subVerifier: "YOUR_SUB_VERIFIER_NAME",
136+
verifierId: "USER'S_VERIFIER_ID",
137+
idToken: "USER'S_ID_TOKEN",
138+
} as JWTLoginParams;
139+
140+
await coreKitInstance.loginWithJWT(jwtLoginParams);
141+
```
142+
143+
## Importing an existing account.
144+
145+
During the first-time login with `Web3AuthMPCCoreKit`, you can import an existing account using the
146+
`importTssKey` parameter. To import a secp256k1 chain account, be sure to provide the private key in
147+
hex format. For an ed25519 chain account, you need to pass the seed.
148+
149+
By default, the ed25519 key is formatted in base58 and is 64 bytes long. This consists of the first
150+
32 bytes as the seed (also known as the private key) and the last 32 bytes as the public key. Ensure
151+
that the first 32 bytes are provided in hexadecimal format when using the ed25519 seed.
152+
153+
```tsx
154+
import { JWTLoginParams } from "@web3auth/mpc-core-kit";
155+
156+
const jwtLoginParams = {
157+
verifier: "YOUR_VERIFIER_NAME",
158+
verifierId: "USER'S_VERIFIER_ID",
159+
idToken: "USER'S_ID_TOKEN",
160+
// focus-next-line
161+
importTssKey: "SECP256K1_PRIVATE_KEY_OR_ED25519_SEED",
162+
} as JWTLoginParams;
163+
164+
await coreKitInstance.loginWithJWT(jwtLoginParams);
165+
```

0 commit comments

Comments
 (0)