Custom JWT Authentication

Oftentimes you may already have JWT tokens for your users. Popular authentication libraries such as Firebase, NextAuth, Stytch, or Privy, already use JWTs to represent the log in state of a user.

In such cases, you can directly pass Crossmint that exact same JWT on API calls, and Crossmint will be able to validate them.

However, you may not currently have JWTs, or you may wish to create a custom JWT scoped only for Crossmint, for additional security reassurance. This guide details the steps necessary to integrate your custom JWT auth with Crossmint.

​

Issue a Custom JWT for Crossmint

On this integration path, you must perform four high level steps:

• Create a public/private keypair
• Generate JWTs
• Expose a JWKS endpoint
• Pass the user’s JWT to Crossmint when using relevant APIs

​

Create the Public/Private keypair

To generate a private key for JWT (JSON Web Token) encryption, you can use several methods depending on your preferred programming language and toolset.

• cli
• nodejs

# Generate the RSA private key
openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:2048

# Convert the private key to a base64 encoded string
openssl base64 -in private_key.pem -out private_key_base64.txt

JWT_PRIVATE_KEY=encoded_private_key_value

rm private_key_base64.txt

# Extract the public key from the private key
openssl rsa -pubout -in private_key.pem -out public_key.pem

# Convert the public key to a base64 encoded string
openssl base64 -in public_key.pem -out public_key_base64.txt

JWT_PUBLIC_KEY=encoded_public_key_value

​

Creating the JSON Web Token

JSON Web Tokens, or JWT for short, are a standard way to encode a series of claims in a payload, that you sign, and can be verified later by a separate party (verifier, in this case, Crossmint) by using public key cryptography.

Crossmint requires you to create a JWT with the following claims:

In addition, you must ensure you follow the following configurations when creating the tokens:

Below is some backend example code to generate a valid JWT for a given user.

First, ensure you have the jose package installed: npm install jose.

import { SignJWT, jwtVerify, importPKCS8, importSPKI } from "jose";
import dotenv from "dotenv";
import { Buffer } from "buffer";

// Load environment variables
dotenv.config();

// Function to generate a JWT using RS256
async function generateJWT(userId) {
    // Decode the private key from base64 and import it
    const privateKeyPEM = Buffer.from(process.env.JWT_PRIVATE_KEY, "base64").toString("utf8");
    const privateKey = await importPKCS8(privateKeyPEM, "RS256");

    // Create and sign the JWT
    const jwt = await new SignJWT()
        .setProtectedHeader({ alg: "RS256" })
        .setIssuer(process.env.CROSSMINT_PROJECT_ID)
        .setSubject(userId)
        .setAudience("crossmint.com")
        .setExpirationTime("10m")
        .sign(privateKey);

    return jwt;
}

​

How to Test

Use the jwt.io token debugger to decode and inspect your tokens.

You can also test locally on your machine decoding your own token and ensuring the fields are properly decoded, using jose.

import { jwtVerify, importSPKI } from "jose";
import dotenv from "dotenv";

// Load environment variables
dotenv.config();

// JWT received from request. Replace this with the actual token you receive.
const jwt = "<your_jwt_here>";

async function verifyJWT(token) {
    // Decode the public key from base64 and import it
    const publicKeyPEM = Buffer.from(process.env.JWT_PUBLIC_KEY, "base64").toString("utf8");
    const publicKey = await importSPKI(publicKeyPEM, "RS256");

    // Verify the JWT
    try {
        const { payload, protectedHeader } = await jwtVerify(token, publicKey, {
            issuer: process.env.CROSSMINT_PROJECT_ID,
            audience: "crossmint.com",
        });

        // Log the verified payload and header
        console.log("Protected Header:", protectedHeader);
        console.log("Payload:", payload);
    } catch (error) {
        console.error("Error verifying JWT:", error);
    }
}

// Call the function with the JWT
verifyJWT(jwt);

​

Expose a JWKS Endpoint

In the step earlier, you learned how to create JWT tokens that Crossmint can interpret. However, in order for Crossmint to validate that these tokens are coming from your project and not an impersonator, Crossmint must validate their signatures against your public key.

You must communicate to Crossmint what your public keys are by using a standard JSON Web Key Set endpoint (JWKS). This is a public API endpoint on your server where you can broadcast what are the current keys valid for your tokens.

The reason why this is implemented as an API, instead of you passing Crossmint a static public key in the console, is in order to support key rotation of your JWT keys in the future.

Below is a very basic example

import { exportJWK } from "jose";

// retrieve public key generated previously
const { publicKey } = await getMyJWTKeyPair();

// Router provided as pseudo-code, adapt to specific framework.
router.get("/.well-known/jwks.json", async (req, res) => {
    // fetch the public key from env
    const publicKeyPEM = Buffer.from(process.env.JWT_PUBLIC_KEY, "base64").toString("utf8");

    // Import the SPKI
    const publicKey = await importSPKI(publicKeyPEM, "RS256");

    // Then export it as a JSON Web Key
    const publicJwk = await exportJWK(publicKey);

    res.send({ keys: [publicJwk] });
});

Once your endpoint is set up, share the URL with your Crossmint Customer Success Engineer.

​

Passing the JWT to Crossmint in API Calls

The last step to complete the loop is that when you’re invoking a Crossmint API, you must pass the JWT.

At this time, the only API that uses it is getOrCreateWallet() in the Smart Wallet SDK, which takes the JWT as an input.

​

Advanced Topics

​

Key Rotation

The private key used for signing your signatures could, over time, be compromised.

Crossmint recommends that you rotate your keys every 6 months to a year.

When performing a rotation, keep the old key if possible as a valid key for a day or so, to ensure none of your existing tokens expire.