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 33a1e3344..1b11638d0 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 @@ -1,65 +1,77 @@ --- slug: /embedded-wallet/custom-auth -title: Use your own auth +title: Overview --- 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 auth to create embedded wallets. +Embedded wallets already support most popular login methods out of the box, but we also give app developers the flexibility to use +embedded wallets with any authentication method. If you have a valid authenticated user, you should be able to easily spin up an +embedded wallet for them irrespective of how they got authenticated. -## How it works +### Usecases -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. +This means that app developers can now -### Bring your own auth server +- Spin up embedded wallets for users using their existing authentication service. For example, if you have a game where players log in using their username and password, you can now easily create wallets when they sign up. +- Integrate with any social login provider. For example, if you have a game where you want to let users login with their Steam or Epic games credentials, you can now use embedded wallets to enable these experiences. +- Use embedded wallets in non-frontend environments. For example, you could authenticate users with SSH and use embedded wallets with CLI tools. +- Build completely custom authentication experiences. For example, you could ask users to verify their credentials with 2FA or passkey before you consider them authenticated and provision wallets for them. -- 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. +## Configuring custom auth + +We offer two options to setup your custom auth, one that is based on the [OIDC (Open ID Connect)](https://openid.net/developers/how-connect-works/) standard, and a generic option that lets you bring your own auth server. You can also use both options together if needed. -### OIDC +### Setting up OIDC compatible auth -- An OIDC auth system has a public-private keypair, where the private key is used to sign auth tokens +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. - 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: +To setup an OIDC compatible auth, enable the first option in the configuration tab of the embedded wallet dashboard +![Custom auth](../assets/customauthdb.png) -### Bring your own auth server +You will be asked to enter the following values +- 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: This is used to verify that thirdweb is the intended user of the token -- 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 +### Setting up generic auth -- 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 - - This is used to verify that thirdweb is the intended user of the token +Generic auth is a lower level option that can be used when 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. -## Authenticating a user +![How generic auth works](../assets/customauth.png) -Once you've logged in with your own auth, you can pass the user's detail to the embedded wallet to authenticate and connect. +To use generic auth, enable the second option in the configuration tab of the embedded wallet dashboard + +![Generic auth dashboard](../assets/customauthdb2.png) + +You will be asked to enter 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. + + +You can also pass a list of headers. These headers will be sent with every request to your verification endpoint. You can use these to authenticate the request. + + + +## Authenticating a user -### Bring your own auth server +### OIDC auth @@ -73,8 +85,8 @@ const embeddedWallet = useEmbeddedWallet(); const handlePostLogin = async (jwt: string) => { await embeddedWallet.connect({ - strategy: "auth_endpoint", - payload, + strategy: "jwt", + jwt, }); }; ``` @@ -95,8 +107,8 @@ const embeddedWallet = new EmbeddedWallet({ }); const authResult = await embeddedWallet.authenticate({ - strategy: "auth_endpoint", - payload, + strategy: "jwt", + jwt, }); const walletAddress = await embeddedWallet.connect({ authResult }); @@ -106,7 +118,9 @@ const walletAddress = await embeddedWallet.connect({ authResult }); -### OIDC + +### Generic auth + @@ -120,8 +134,8 @@ const embeddedWallet = useEmbeddedWallet(); const handlePostLogin = async (jwt: string) => { await embeddedWallet.connect({ - strategy: "jwt", - jwt, + strategy: "auth_endpoint", + payload, }); }; ``` @@ -142,8 +156,8 @@ const embeddedWallet = new EmbeddedWallet({ }); const authResult = await embeddedWallet.authenticate({ - strategy: "jwt", - jwt, + strategy: "auth_endpoint", + payload, }); const walletAddress = await embeddedWallet.connect({ authResult }); @@ -151,3 +165,4 @@ const walletAddress = await embeddedWallet.connect({ authResult }); + diff --git a/docs/onboarding/21 Embedded Wallet/assets/customauth.png b/docs/onboarding/21 Embedded Wallet/assets/customauth.png new file mode 100644 index 000000000..d45015df4 Binary files /dev/null and b/docs/onboarding/21 Embedded Wallet/assets/customauth.png differ diff --git a/docs/onboarding/21 Embedded Wallet/assets/customauthdb.png b/docs/onboarding/21 Embedded Wallet/assets/customauthdb.png new file mode 100644 index 000000000..7b3682e19 Binary files /dev/null and b/docs/onboarding/21 Embedded Wallet/assets/customauthdb.png differ diff --git a/docs/onboarding/21 Embedded Wallet/assets/customauthdb2.png b/docs/onboarding/21 Embedded Wallet/assets/customauthdb2.png new file mode 100644 index 000000000..f5ca42158 Binary files /dev/null and b/docs/onboarding/21 Embedded Wallet/assets/customauthdb2.png differ diff --git a/docs/onboarding/22 NFT Checkouts/0 Overview.mdx b/docs/onboarding/22 NFT Checkouts/0 Overview.mdx index f86a26ee7..545026783 100644 --- a/docs/onboarding/22 NFT Checkouts/0 Overview.mdx +++ b/docs/onboarding/22 NFT Checkouts/0 Overview.mdx @@ -42,7 +42,10 @@ Card and other fiat payments are accepted from all 50 US states and US-sanctione | Sepolia | ETH | | Zora Testnet | ETH | -\* - ERC-20 payments are available for pro or enterprise customers only. +<<<<<<< HEAD \* - ERC-20 payments are available for pro or enterprise customers only. +======= \* - ERC-20 tokens are available for pro or enterprise customers only. + +> > > > > > > main ### Fraud prevention & chargeback protection diff --git a/docs/onboarding/22 NFT Checkouts/1b Advanced Guides/5 Thirdweb Contracts.mdx b/docs/onboarding/22 NFT Checkouts/1b Advanced Guides/5 Thirdweb Contracts.mdx new file mode 100644 index 000000000..3727e6a86 --- /dev/null +++ b/docs/onboarding/22 NFT Checkouts/1b Advanced Guides/5 Thirdweb Contracts.mdx @@ -0,0 +1,91 @@ +--- +slug: /checkouts/thirdweb-contracts +title: thirdweb Contracts +--- + +## Integration + +For some thirdweb contracts, set `contractArgs` when creating [Shareable Checkout Links](/checkouts/checkout-link), [One-Time Checkout Links](/checkouts/one-time-checkout-link), or [Checkout Elements](/checkouts/elements). + +### Signature Drop + +This is an ERC-721A contract where the NFT metadata is unique but the claim configuration can be modified for each buyer by creating a _signature_ on your backend. If you don't plan to use signatures, you should consider using the [NFT Drop](https://portal.thirdweb.com/pre-built-contracts/nft-drop) contract. + +To customize the NFT metadata, allow dynamic pricing, or enforce an off-chain allowlist, generate a signature on your backend and set `contractArgs`: + +```typescript +const signatureDrop = thirdwebSdk.getContract('signature-drop'); + +// Generate a signature from a payload that provides some configuration override. +const payload = { + to: buyerWalletAddress, + price: "0.01", + mintStartTime: new Date(0), +}; +const signature = await signatureDrop.signature.generate(payload); + +// Set contractArgs with the payload and signature. +contractArgs = { + payload, + signature, +} +``` + +See guide: [Create an ERC721A NFT Drop with Signature-Based Minting](https://blog.thirdweb.com/guides/signature-drop/) + +### NFT Drop + +This is an ERC-721A contract where the NFT metadata is unique but the claim configuration is identical for all buyers. No `contractArgs` should be set. + +### Edition Drop + +This is an ERC-1155 contract where the NFT metadata and claim configuration is identical for all buyers. Set `contractArgs` with the token ID to mint: + +```typescript +contractArgs = { tokenId: "0" } +``` + +### Marketplace + +This is a contract that allows other users to purchase already-minted NFTs. Set `contractArgs` with an array of the marketplace listing IDs of each of the direct listing: + +```typescript +contractArgs = { + listings: [ + { listingId: "0" }, + { listingId: "1" }, + ... + ] +} +``` + +## Configure the Claim Condition + +Your thirdweb contract must have at least one active claim condition, meaning the **When will this phase start?** date is in the past. + +![Claim Condition Configuration Image](https://files.readme.io/994d683-image.png) + +Helpful tips for each field: + +| Field | Notes | +|-------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **When will this phase start?** | thirdweb can only mint NFTs after this date. | +| **How many NFTs will you drop in this phase?** | Remember to create NFTs on the **NFTs** tab for NFT Drop contracts. | +| **How much do you want to charge to claim each NFT?** | For Mumbai, this price must be ≤ 0.0001 MATIC.
For Goerli, this price must be ≤ 0.0001 ETH.

On production, there is a $2,000 price limit. Please fill out [this Typeform](https://fw3786mcxwl.typeform.com/to/B0xIFoiu) to request an increase. | +| **What currency do you want to use?** | Supported currencies on thirdweb:
- Mumbai: MATIC
- Polygon: MATIC, USDC, WETH
- Goerli: ETH
- Ethereum: ETH, USDC | +| **Who can claim NFTs during this phase?** | If you have an allowlist, please add thirdweb's minter wallets.
Otherwise leave this blank. | +| **How many NFTs can be claimed per transaction?** | This value must be Unlimited. Otherwise thirdweb's minter wallets will not be able to mint more than this amount. | +| **How many seconds do wallets have to wait in-between claiming?** | This value must be 0. Otherwise thirdweb's minter wallets will fail when many mints occur at once. | + +## Debug common blockchain error responses + +| Error Message | Description | Solution | +|-------------------|----------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `!Qty` | The buyer is attempting to purchase more than allowed per wallet. | **:warning: Your Claim Condition must allow thirdweb Wallets to mint an unlimited amount.**

The **How many NFTs can be claimed per transaction?** setting must be set to Unlimited. Alternatively, allow thirdweb's minter wallets to mint the full supply in a snapshot. | +| `!MaxSupply` | The buyer is attempting to purchase more than the available supply, or the drop is sold out. | Allow more NFTs to be sold, or prevent buyers from navigating to the checkout page if sold out. | +| `cant claim yet` | There is no claim phase, or the claim phase has not started. | Wait until the claim phase has started, or set one claim phase's start date to a past date. | +| `!PriceOrCurrency`| thirdweb sent the incorrect amount or currency to the contract. | thirdweb may be auto-detecting the price incorrectly. Please reach out on [Discord](https://discord.gg/thirdweb). | + +_Source: Drop.sol from thirdweb contracts_ + +If your transactions are failing for these reasons, please update the active **Claim Condition** on your thirdweb contract.