Create and recover signers

Create and manage embedded wallets for your users

Understanding embedded signers#

To create wallets for your users during the login flow, you need to configure the embedded signer. The configuration depends on your chosen recovery method, so it's important to decide on your recovery strategy first.

Embedded state

Always wait for the embedded state to be ready before using the embedded signer. See the integration guide.

Choosing a Recovery Method#

There are two core recovery modes for Openfort embedded signers:

Automatic Recovery: Recovery share is encrypted using project and Openfort entropy
User-based Recovery: Recovery share is encrypted using user-provided entropy (password)

Automatic recovery setup#

Automatic recovery provides smooth UX but requires careful security considerations. You can implement it using either Openfort Auth or a third-party authentication provider:

When using automatic recovery, Shield generates a password that is used for the encryption of the recovery share. The full encryption key can only be accessed if the decryption request includes the user's auth token.

Encryption share

When using automatic recovery, its very important to ensure that the encryption share should not be available from the client side of the application.

From your backend, you should have an endpoint that generates an encryption session for the user. This endpoint should be protected and only accessible by the user who is requesting the encryption session (i.e. the user who is logging in).

An encryption session is requested every time configureEmbeddedSigner is called. The encryption session is only valid for a single use.

For example, in a Next.js API route, you can create an endpoint like this:

protected-create-encryption-session.ts

openfortAdminConfig.ts

import openfort from './openfortAdminConfig';
export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
    const session = await openfort.registerRecoverySession('YOUR_SHIELD_PUBLISHABLE_KEY', 'YOUR_SHIELD_SECRET_KEY', 'YOUR_SHIELD_ENCRYPTION_SHARE')
    res.status(200).send({
        session: session,
    });
}

Once we've secured the backend we setup the client side:

openfortManager.cs

encryptionSession.cs

using System;
using System.Threading.Tasks;
using UnityEngine;
using UnityEngine.Networking;
using Openfort.OpenfortSDK;
using Openfort.OpenfortSDK.Model;
using static Clients.Shield;
public class EmbeddedSignerManager : MonoBehaviour 
{
    private OpenfortSDK openfort;
    // Setup with Openfort authentication
    public async Task SetupAutomaticRecoveryWithOpenfort(string email, string password)
    {
        try 
        {
            // Sign up the user
            AuthResponse response = await openfort.SignUpWithEmailPassword(email, password);
            string token = response.Token;
            
            // Get encryption session from your backend
            string encryptionSession = await GetEncryptionSession();
            
            // Configure the signer
            int chainId = 80002; // Polygon Amoy testnet
            ShieldAuthentication shieldConfig = new ShieldAuthentication(
                ShieldAuthType.Openfort, 
                token
            )
            {
                EncryptionSession = encryptionSession
            };
            EmbeddedSignerRequest request = new EmbeddedSignerRequest(chainId, shieldConfig);
            await openfort.ConfigureEmbeddedSigner(request);
            
            Debug.Log("Automatic recovery setup complete");
        }
        catch (Exception e)
        {
            Debug.LogError($"Error setting up automatic recovery: {e.Message}");
        }
    }
}

We recommend enabling user-based recovery for users. This is especially important to enforce as the value of assets in a user's wallet grows.

User-based recovery setup#

Password recovery

Require that users set a password when the wallet is created, enforcing password-based recovery from the start.

If encrypted by user-provided entropy, only the user can decrypt the recovery share. Openfort never sees or the user's password. Therefore, if you're not planning to ever user the automatic recovery mode, you can use the encryption share in the client side of the application.

using Openfort.OpenfortSDK;
using Openfort.OpenfortSDK.Model;
public class openfortManager: MonoBehaviour 
{
    private OpenfortSDK Openfort;
    private async void AuthAndSetPassordRecoveryMethod(string email, string password, string recoveryPassword)
    {
        AuthResponse response = await Openfort.SignUpWithEmailPassword(email, password);
        string token = response.Token;
        int chainId = 80002;
        ShieldAuthentication shieldConfig = new ShieldAuthentication(ShieldAuthType.Openfort, token);
        EmbeddedSignerRequest request = new EmbeddedSignerRequest(chainId, shieldConfig, recoveryPassword);
        await Openfort.ConfigureEmbeddedSigner(request);
    }
}

Pregeneration#

Openfort also allows you to pregenerate embedded wallets for your users, even before they first login to your game. Please see our pregeneration guide for more.