diff --git a/docs/onboarding/21 Embedded Wallet/4 Custom Auth/1 Bring your Auth.mdx b/docs/onboarding/21 Embedded Wallet/4 Custom Auth/1 Bring your Auth.mdx
index 355e9694b..33a1e3344 100644
--- a/docs/onboarding/21 Embedded Wallet/4 Custom Auth/1 Bring your Auth.mdx
+++ b/docs/onboarding/21 Embedded Wallet/4 Custom Auth/1 Bring your Auth.mdx
@@ -3,25 +3,52 @@ slug: /embedded-wallet/custom-auth
title: Use your own auth
---
-import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
+import Tabs from "@theme/Tabs";
import QuickstartCard from "@components/QuickstartCard";
By default, the embedded wallet service handles two things: auth, and spinning up crypto wallets tied to the auth. We require
valid authentication to ensure a wallet is created for the right person.
-If you already have your own auth and only want to spin up wallets, we offer a simple way to hook up any **OpenID Connect ("OIDC") compatible** auth to create embedded wallets.
+If you already have your own auth and only want to spin up wallets, we offer a simple way to hook up any auth to create embedded wallets.
## How it works
+We offer two kinds of custom auth. One that is based on the OIDC standard, and one that is is based on you having you bring your own auth server.
+
+### Bring your own auth server
+
+- You have your own auth server that you use to authenticate users
+- When a user logs in, you are able to generate a public identifier that allows you to identify the user.
+- You can pass this identifier to the embedded wallet to generate a wallet for the user.
+- When verifying the user, we will hit an endopint that you provide to verify the user's identity.
+- We will then generate a wallet for the user if the provided payload is valid.
+
+### OIDC
+
- An OIDC auth system has a public-private keypair, where the private key is used to sign auth tokens
- The public key is uploaded to a public URL in JWKS format. The standard location is `https://{domain}.com/.well-known/jwks.json`
- When a user logs in, a JWT token called the idToken is generated and signed by the private key. The OIDC spec provides an interface for fields that are used in this token.
-- We use the public key to verify that the JWT was signed correctly, and proceed to generate a wallet based on the `sub` (user identifier) value of the idToken.
+- This JWT is then passed to the embedded wallet to generate a wallet for the user.
+- We will verify the JWT against the public key to verify that the JWT was signed correctly. Upon successful verification, we will proceed to generate a wallet based on the `sub` (user identifier) value of the idToken.
## Configuration Setup
In your API key settings, click edit, look for "Custom Auth" and provide the following values:
+### Bring your own auth server
+
+- An endpoint that we can hit to verify the user's identity
+ - This endpoint should accept a POST request with a JSON body containing the following fields:
+ - `payload`: This will correspont to the public identifier that was generated for your user.
+ - The endpoint should return a JSON body containing the following fields:
+ - `userId`: A uid for the user. Note that you can only create one wallet per `userId` at this point
+ - `email` (optional): If provided, the user will be able to access the same account outside of the platform for things like private key export // using with wallet connect etc.
+ - `exp` (optional): An expiration date for the user's wallet session. By default a session is 7 days long.
+- A list of custom headers (optional)
+ - These headers will be sent with every request to your verification endpoint. You can use these to authenticate the request.
+
+### OIDC
+
- The URL of the JWKS file (public key)
- This is used to verify the token was signed by you.
- The `aud` value of the idToken
@@ -29,7 +56,57 @@ In your API key settings, click edit, look for "Custom Auth" and provide the fol
## Authenticating a user
-Once you've logged in with your own auth, you can pass the user's JWT to the embedded wallet to authenticate and connect.
+Once you've logged in with your own auth, you can pass the user's detail to the embedded wallet to authenticate and connect.
+
+### Bring your own auth server
+
+
+
+
+
+In React and React Native, the `useEmbeddedWallet()` hook handles authentication and connection states.
+
+```typescript
+import { useEmbeddedWallet } from "@thirdweb-dev/react"; // or /react-native
+
+const embeddedWallet = useEmbeddedWallet();
+
+const handlePostLogin = async (jwt: string) => {
+ await embeddedWallet.connect({
+ strategy: "auth_endpoint",
+ payload,
+ });
+};
+```
+
+
+
+
+
+In other frameworks, use your own instance of the wallet to authenticate and connect.
+
+```typescript
+import { EmbeddedWallet } from "@thirdweb-dev/wallets";
+import { Goerli } from "@thirdweb-dev/chains";
+
+const embeddedWallet = new EmbeddedWallet({
+ chain: Goerli, // chain to connect to
+ clientId: "YOUR_CLIENT_ID", // Your thirdweb client ID
+});
+
+const authResult = await embeddedWallet.authenticate({
+ strategy: "auth_endpoint",
+ payload,
+});
+
+const walletAddress = await embeddedWallet.connect({ authResult });
+```
+
+
+
+
+
+### OIDC
@@ -51,7 +128,7 @@ const handlePostLogin = async (jwt: string) => {
-
+
In other frameworks, use your own instance of the wallet to authenticate and connect.
diff --git a/docs/onboarding/21 Embedded Wallet/4 Custom Auth/2 custom-auth-server.mdx b/docs/onboarding/21 Embedded Wallet/4 Custom Auth/2 custom-auth-server.mdx
index aa8764ef3..fed4fc4af 100644
--- a/docs/onboarding/21 Embedded Wallet/4 Custom Auth/2 custom-auth-server.mdx
+++ b/docs/onboarding/21 Embedded Wallet/4 Custom Auth/2 custom-auth-server.mdx
@@ -3,101 +3,138 @@ slug: /embedded-wallet/custom-auth-server
title: Custom Auth Server
---
+import TabItem from "@theme/TabItem";
+import Tabs from "@theme/Tabs";
+
# Create a custom auth server
-Learn how to integrate your auth backend with our embedded wallets solution so you can onboard your users into web3 seamlessly.
+Learn how to integrate your auth backend with our embedded wallets solution so you can onboard your users into web3 seamlessly.
-This guide will show you how to create your own Auth Server. By doing so, you can have full control over user authentication and data security. This allows you to ensure that your application meets specific compliance requirements while also providing a customized sign-in experience.
+This guide will show you how to create your own Auth Server that is compatible with the `auth_endpoint` strategy. By doing so, you can have full control over user authentication and data security. This allows you to ensure that your application meets specific compliance requirements while also providing a customized sign-in experience.
:::caution
This guide is simplified for demonstration purposes and is not ready for production use. When modifying it for production, secure your endpoints and avoid hard-coding secrets or sensitive information. We recommend using environment variables and secret managers.
:::
-### Setup
+## 5 minute quickstart
-1. Create a new directory for your project and navigate to it in your CLI
+1. Navigate to Wallets > [Embedded Wallets](https://thirdweb.com/dashboard/wallets/embedded) in the thirdweb dashboard.
+2. Create a thirdweb API key if you don't have one or select an existing key to use for this project. [Learn more about API keys.](https://portal.thirdweb.com/api-keys)
- ```bash
- mkdir jwt-auth-server
- cd jwt-auth-server
- ```
+ 
-2. Initialize a new Node.js application
+3. Allowlist domain or bundle ids in Access Restrictions.
+4. Navigate to the Configuration view and enable **Custom Auth Endpoint**
- ```bash
- npm init -y
+ 
- yarn init -y
- ```
+5. Set the Auth Endpoint URL to `https://embedded-wallet.thirdweb.com/api/2023-11-30/embedded-wallet/auth/test-custom-auth-endpoint` for testing purposes. You will replace this later with your own auth server endpoint to verify the `payload`.
+6. Save the configuration.
+7. Copy the client ID.
+8. In your preferred thirdweb client SDK, pass the payload you retrieved from logging in to the server.
-3. Install the necessary packages
+You can now auth into the wallet and use it to sign transactions like so (see [use your own auth for more](/embedded-wallet/custom-auth)):
- ```bash
- npm install express jsonwebtoken
- ```
+
+
-### **Generate RSA Key Pair:**
+In React and React Native, the `useEmbeddedWallet()` hook handles authentication and connection states.
-1. To generate a private and a public key run
+```typescript
+import { useEmbeddedWallet } from "@thirdweb-dev/react"; // or /react-native
- ```bash
- ssh-keygen -t rsa -b 2048 -m PEM -f keys/rsa.key
- ```
+const embeddedWallet = useEmbeddedWallet();
-2. To create the output file run
+const handlePostLogin = async () => {
+ await embeddedWallet.connect({
+ strategy: "auth_endpoint",
+ // in production this would be your public identifier for the user
+ payload: JSON.stringify({ userId:"ANY_RANDOM_ID_HERE" }),
+ encryptionKey: "ANY_RANDOM_STRING_HERE"
+ });
+};
+```
- ```bash
- openssl rsa -in keys/rsa.key -pubout -outform PEM -out keys/rsa.key.pub
- ```
+
+
-### **Convert Public Key to JSON Web Key Set (JWKS):**
+In other frameworks, use your own instance of the wallet to authenticate and connect.
-1. Display the public key:
+```typescript
+import { EmbeddedWallet } from "@thirdweb-dev/wallets";
+import { Goerli } from "@thirdweb-dev/chains";
- ```bash
- cat keys/rsa.key.pub
- ```
+const embeddedWallet = new EmbeddedWallet({
+ chain: Goerli, // chain to connect to
+ clientId: "YOUR_CLIENT_ID", // Your thirdweb client ID
+});
+
+const authResult = await embeddedWallet.authenticate({
+ strategy: "auth_endpoint",
+ payload: JSON.stringify({ userId:"ANY_RANDOM_ID_HERE" }),
+ encryptionKey: "ANY_RANDOM_STRING_HERE"=
+});
+
+const walletAddress = await embeddedWallet.connect({ authResult });
+```
-2. Copy the displayed public key.
-3. Convert your public key to a JWK using an online JWK Creator tool. We recommend using [JWK Creator by Russel Davies](https://github.com/russelldavies/jwk-creator).
+
+
- 1. Paste the public key, set Key ID as `0` (arbitrary string, must match when signing JWT), and then note down the generated JWK.
+A persistent, cross-platform wallet is now created for your user!
- 
+Of course, you would use your own auth server instead of the one we provided. The rest of this guide will show you how to create your own auth server.
-4. Create a `jwks.json` in the project root and place the generated JWK in a `keys` array.
+### Setup
+
+The following steps will show you how to create a simple auth server that can be used with the embedded wallet.
+
+At a high level, the auth server will:
+
+1. Handle login for the user into your application.
+2. Have a way to get a public identifier for the user.
+3. Have an endpoint to verify the public identifier and return some basic information about the user
+
+Steps 1 and 2 are up to you to implement. You can use any auth strategy you want.
+
+The endpoint in step 3 is what your register as your auth endpoint on the thirdweb dashboard.
+
+Here's a high level diagram:
+
+
+1. Create a new directory for your project and navigate to it in your CLI
+
+ ```bash
+ mkdir custom-auth-server
+ cd custom-auth-server
+ ```
+
+2. Initialize a new Node.js application
```bash
- {
- "keys": [
- {
- ... JWK ...
- }
- ]
- }
+ npm init -y
+
+ yarn init -y
```
### **Create the Server:**
-1. In the `jw-auth-server` directory, create a file at the root named `server.js` and paste the following:
+1. In the `custom-auth-server` directory, create a file at the root named `server.js` and paste the following:
```jsx
const express = require("express");
const fs = require("fs");
- const jwt = require("jsonwebtoken");
const app = express();
const PORT = process.env.PORT || 3000;
- const PRIVATE_KEY = fs.readFileSync("./keys/rsa.key", "utf8");
- const jwks = require("./jwks.json");
-
const users = [
{ id: 1, email: "user@example.com", password: "password123" },
];
app.use(express.json());
+ // This is what your app calls to login a user and get a public identifier for the user (otherwise known as the payload)
app.post("/login", (req, res) => {
const { email, password } = req.body;
const user = users.find(
@@ -105,24 +142,24 @@ This guide is simplified for demonstration purposes and is not ready for product
);
if (!user) return res.status(401).send({ message: "Invalid credentials" });
- const payload = {
- iss: "http://your-domain.com",
- sub: user.id.toString(),
- aud: "EpicGame",
- email: user.email,
- exp: Math.floor(Date.now() / 1000) + 3600,
- };
-
- const token = jwt.sign(payload, PRIVATE_KEY, {
- algorithm: "RS256",
- keyid: "0",
- });
-
- res.send({ token });
+ res.send({ payload: user.id });
});
+ // This is a sample endpoint that yuou would register on the thirdweb dashboard for us to verify the payload
+ app.get("/thirdweb-will-call-this", (req, res) => {
+ const { payload } = req.body;
+ if (!payload) return res.status(401).send({ message: "Invalid credentials" });
- app.get("/.well-known/jwks.json", (req, res) => {
- res.json(jwks);
+ // you would write your own logic here to verify the payload here
+ const user = users.find((u) => u.id === payload);
+ if (!user) return res.status(401).send({ message: "Invalid credentials" });
+
+ // once the user is successfully verified, you can return the following field
+ return res.send({
+ userId: user.id,
+ // the last two fields here are optional
+ email: user.email,
+ exp: Math.floor(Date.now() / 1000) + 60 * 60 * 24 * 30,
+ });
});
app.listen(PORT, () => {
@@ -130,8 +167,6 @@ This guide is simplified for demonstration purposes and is not ready for product
});
```
-2. Replace `http://your-domain.com` with the actual domain for the application.
-
### **Test Locally**
1. Start the server:
@@ -146,36 +181,10 @@ This guide is simplified for demonstration purposes and is not ready for product
curl -X POST http://localhost:3000/login -H "Content-Type: application/json" -d '{"email": "user@example.com", "password": "password123"}'
```
-3. Test JWKS:
-
- ```bash
- curl http://localhost:3000/.well-known/jwks.json
- ```
-
### **Deploy**
To deploy the server, you can use use services such as [Zeet](https://zeet.co/) or [Docker](https://www.docker.com/).
-Once deployed, replace `http://localhost:3000` in the JWT payload with your actual domain
-
### **Integrate Embedded Wallets**
-1. Navigate to Wallets > [Embedded Wallets](https://thirdweb.com/dashboard/wallets/embedded) in the thirdweb dashboard.
-2. Create a thirdweb API key if you don’t have one or select an existing key to use for this project. [Learn more about API keys.](https://portal.thirdweb.com/api-keys)
-
- 
-
-3. Allowlist domain or bundle ids in Access Restrictions.
-4. Navigate to the Configuration view and enable **Custom JSON Web Token**
-
- 
-
-5. Set the JWKS URI to `your-domain/.well-known/jwks.json`
-6. Set the AUD to `EpicGame` or the value you set as the aud in the `server.js` file.
-
- 
-
-7. Copy the client ID.
-8. In your preferred thirdweb client SDK, pass the JWT you retrieved from logging in to the server.
-
-A persistent, cross-platform wallet is now created for your user.
+Refer top the [quickstart above](#5-minute-quickstart) to integrate the embedded wallet into your application.
\ No newline at end of file
diff --git a/docs/onboarding/21 Embedded Wallet/4 Custom Auth/3 custom-jwt-auth-server.mdx b/docs/onboarding/21 Embedded Wallet/4 Custom Auth/3 custom-jwt-auth-server.mdx
new file mode 100644
index 000000000..06753a6b1
--- /dev/null
+++ b/docs/onboarding/21 Embedded Wallet/4 Custom Auth/3 custom-jwt-auth-server.mdx
@@ -0,0 +1,181 @@
+---
+slug: /embedded-wallet/custom-jwt-auth-server
+title: Custom JWT Auth Server
+---
+
+# Create a custom JWT auth server
+
+Learn how to integrate your auth backend with our embedded wallets solution so you can onboard your users into web3 seamlessly.
+
+This guide will show you how to create your own Auth Server that is compatible with the JWT auth strategy. By doing so, you can have full control over user authentication and data security. This allows you to ensure that your application meets specific compliance requirements while also providing a customized sign-in experience.
+
+:::caution
+This guide is simplified for demonstration purposes and is not ready for production use. When modifying it for production, secure your endpoints and avoid hard-coding secrets or sensitive information. We recommend using environment variables and secret managers.
+:::
+
+### Setup
+
+1. Create a new directory for your project and navigate to it in your CLI
+
+ ```bash
+ mkdir jwt-auth-server
+ cd jwt-auth-server
+ ```
+
+2. Initialize a new Node.js application
+
+ ```bash
+ npm init -y
+
+ yarn init -y
+ ```
+
+3. Install the necessary packages
+
+ ```bash
+ npm install express jsonwebtoken
+ ```
+
+### **Generate RSA Key Pair:**
+
+1. To generate a private and a public key run
+
+ ```bash
+ ssh-keygen -t rsa -b 2048 -m PEM -f keys/rsa.key
+ ```
+
+2. To create the output file run
+
+ ```bash
+ openssl rsa -in keys/rsa.key -pubout -outform PEM -out keys/rsa.key.pub
+ ```
+
+### **Convert Public Key to JSON Web Key Set (JWKS):**
+
+1. Display the public key:
+
+ ```bash
+ cat keys/rsa.key.pub
+ ```
+
+2. Copy the displayed public key.
+3. Convert your public key to a JWK using an online JWK Creator tool. We recommend using [JWK Creator by Russel Davies](https://github.com/russelldavies/jwk-creator).
+
+ 1. Paste the public key, set Key ID as `0` (arbitrary string, must match when signing JWT), and then note down the generated JWK.
+
+ 
+
+4. Create a `jwks.json` in the project root and place the generated JWK in a `keys` array.
+
+ ```bash
+ {
+ "keys": [
+ {
+ ... JWK ...
+ }
+ ]
+ }
+ ```
+
+### **Create the Server:**
+
+1. In the `jw-auth-server` directory, create a file at the root named `server.js` and paste the following:
+
+ ```jsx
+ const express = require("express");
+ const fs = require("fs");
+ const jwt = require("jsonwebtoken");
+
+ const app = express();
+ const PORT = process.env.PORT || 3000;
+
+ const PRIVATE_KEY = fs.readFileSync("./keys/rsa.key", "utf8");
+ const jwks = require("./jwks.json");
+
+ const users = [
+ { id: 1, email: "user@example.com", password: "password123" },
+ ];
+
+ app.use(express.json());
+
+ app.post("/login", (req, res) => {
+ const { email, password } = req.body;
+ const user = users.find(
+ (u) => u.email === email && u.password === password,
+ );
+ if (!user) return res.status(401).send({ message: "Invalid credentials" });
+
+ const payload = {
+ iss: "http://your-domain.com",
+ sub: user.id.toString(),
+ aud: "EpicGame",
+ email: user.email,
+ exp: Math.floor(Date.now() / 1000) + 3600,
+ };
+
+ const token = jwt.sign(payload, PRIVATE_KEY, {
+ algorithm: "RS256",
+ keyid: "0",
+ });
+
+ res.send({ token });
+ });
+
+ app.get("/.well-known/jwks.json", (req, res) => {
+ res.json(jwks);
+ });
+
+ app.listen(PORT, () => {
+ console.log(`Server started on port ${PORT}`);
+ });
+ ```
+
+2. Replace `http://your-domain.com` with the actual domain for the application.
+
+### **Test Locally**
+
+1. Start the server:
+
+ ```bash
+ node server.js
+ ```
+
+2. Test login:
+
+ ```bash
+ curl -X POST http://localhost:3000/login -H "Content-Type: application/json" -d '{"email": "user@example.com", "password": "password123"}'
+ ```
+
+3. Test JWKS:
+
+ ```bash
+ curl http://localhost:3000/.well-known/jwks.json
+ ```
+
+### **Deploy**
+
+To deploy the server, you can use use services such as [Zeet](https://zeet.co/) or [Docker](https://www.docker.com/).
+
+Once deployed, replace `http://localhost:3000` in the JWT payload with your actual domain
+
+### **Integrate Embedded Wallets**
+
+1. Navigate to Wallets > [Embedded Wallets](https://thirdweb.com/dashboard/wallets/embedded) in the thirdweb dashboard.
+2. Create a thirdweb API key if you don’t have one or select an existing key to use for this project. [Learn more about API keys.](https://portal.thirdweb.com/api-keys)
+
+ 
+
+3. Allowlist domain or bundle ids in Access Restrictions.
+4. Navigate to the Configuration view and enable **Custom JSON Web Token**
+
+ 
+
+5. Set the JWKS URI to `your-domain/.well-known/jwks.json`
+6. Set the AUD to `EpicGame` or the value you set as the aud in the `server.js` file.
+
+ 
+
+7. Copy the client ID.
+8. In your preferred thirdweb client SDK, pass the JWT you retrieved from logging in to the server.
+
+A persistent, cross-platform wallet is now created for your user.
diff --git a/docs/onboarding/21 Embedded Wallet/4 Custom Auth/3 Integrate Firebase Auth.mdx b/docs/onboarding/21 Embedded Wallet/4 Custom Auth/4 Integrate Firebase Auth.mdx
similarity index 100%
rename from docs/onboarding/21 Embedded Wallet/4 Custom Auth/3 Integrate Firebase Auth.mdx
rename to docs/onboarding/21 Embedded Wallet/4 Custom Auth/4 Integrate Firebase Auth.mdx
diff --git a/docs/onboarding/21 Embedded Wallet/assets/ew-custom-auth-config.png b/docs/onboarding/21 Embedded Wallet/assets/ew-custom-auth-config.png
new file mode 100644
index 000000000..771d19c1f
Binary files /dev/null and b/docs/onboarding/21 Embedded Wallet/assets/ew-custom-auth-config.png differ
diff --git a/docs/onboarding/21 Embedded Wallet/assets/ew-custom-auth-flow.png b/docs/onboarding/21 Embedded Wallet/assets/ew-custom-auth-flow.png
new file mode 100644
index 000000000..7870ef803
Binary files /dev/null and b/docs/onboarding/21 Embedded Wallet/assets/ew-custom-auth-flow.png differ