Forem: Roberto Yamanaka

Integrating GraphQL Codegen + React Query + Clerk JWT Tokens

Roberto Yamanaka — Wed, 03 Apr 2024 02:22:34 +0000

Use Case

So, you are using GraphQL Codegen to automatically generate your GraphQL schema (and types) based on your GraphQL schema in the backend.

Using Codegen gives you a better experience, since it automatically generates you the types and custom code/hooks you want. You can even automatically generate your React Query Hooks to fetch the GraphQL data. Life is great.

However... there is one issue. How do these automatically generated hooks and functions handle the authentication?

Let's dive into how we can achieve this: authentication + generated code

Basic setup

We'll start by creating a new NextJS project (vanilla React works just fine).

I'll name the project codegen-jwt and use the default configuration from Next

What is your project named? my-app
Would you like to use TypeScript? No / Yes
Would you like to use ESLint? No / Yes
Would you like to use Tailwind CSS? No / Yes
Would you like to use `src/` directory? No / Yes
Would you like to use App Router? (recommended) No / Yes
Would you like to customize the default import alias (@/*)? No / Yes
What import alias would you like configured? @/*

Next, lets install GraphQL, Codegen with some useful plugins and Tanstack React Query to test our generated query hooks.

npm i graphql axios @tanstack/react-query
npm i -D typescript ts-node @graphql-codegen/cli @graphql-codegen/client-preset @parcel/watcher @graphql-codegen/typescript-react-query

Now lets add our Auth provider Clerk. You can follow these instructions for a quick setup.

npm install @clerk/nextjs

Prepare the GraphQL Queries and source

For this tutorial we will use a public GraphQL schema for our Codegen

https://graphql.anilist.co

Now let's create some GraphQL queries that Codegen will take to generate the types for us.

Create a new file called codegen/queries.graphql and add this query.

query findAnimeById($id: Int) {
  Media (id: $id, type: ANIME) {
    id
    title {
      romaji
      english
      native
    }
  }
}

Codegen will use this to generate the types and the react-query hooks.

Building our Code Generator

Ok! Now that we have the setup ready. Let's write our codegen/codegen.ts file. This serves as the Instructions for Codegen.

import type { CodegenConfig } from "@graphql-codegen/cli";

const config: CodegenConfig = {
  overwrite: true,
  schema: "https://graphql.anilist.co",
  documents: 'codegen/**/*.graphql',
  generates: {
    "graphql/__generated__/graphql.ts": {
      plugins: [
        "typescript",
        "typescript-operations",
        "typescript-react-query",
      ],
      config: {
        reactQueryVersion: "auto",
        exposeQueryKeys: true,
        exposeFetcher: true,
        fetcher: {
          func: "@/codegen/fetcher#useFetchGraphQLData",
          isReactHook: true,
        },
      },
    },
  },
};

export default config;

The most important part of this is the fetcher config. This is where we define all the configuration for the fetcher Codegen will use.

Our fetcher.tsx has a custom hook that will handle the calls to the backend. Here we will pass our Clerk JWT Token to the Headers to authenticate using the useAuth hook.

If your auth provider doesn't use hooks for obtaining the JWT Token, you can create a simple Ts function to obtain it and then add it to your headers. Just set isReactHook: false

Here is that codegen/fetcher.tsx file.

import { useAuth } from "@clerk/nextjs";
import axios, { AxiosError, isAxiosError } from "axios";

interface GraphQLResponse<T> {
  data: T;
  errors?: { message: string }[];
}

export const useFetchGraphQLData = <TData, TVariables>(
  query: string
): ((variables?: TVariables) => Promise<TData>) => {
  const { getToken } = useAuth();
  const url =
    "https://dummyjson.com"; // Replace this with your GraphQL API URL

  return async (variables?: TVariables) => {
    const token = await getToken();

    try {
      const response = await axios.post<GraphQLResponse<TData>>(
        url,
        {
          query,
          variables,
        },
        {
          headers: {
            "Content-Type": "application/json",
            Authorization: token ? `Bearer ${token}` : "",
          },
        }
      );

      if (response.data.errors) {
        throw new Error(response.data.errors[0].message);
      }

      return response.data.data;
    } catch (error) {
      if (isAxiosError(error)) {
        const serverError = error as AxiosError<GraphQLResponse<unknown>>;
        if (serverError && serverError.response) {
          const errorMessage =
            serverError.response.data.errors?.[0]?.message ||
            "Error in GraphQL request";
          throw new Error(errorMessage);
        }
      }
      throw error;
    }
  };
};

And just like that you can add JWT tokens to your graphQL queries!

Running Codegen

Now that we have everything in place, lets generate the codegen with this command.

npx graphql-codegen --config codegen/codegen.ts

If we go to the generated file graphql/__generated__/graphql.ts we can see that it automatically created the React Query Hook.

export const useFindAnimeByIdQuery = <
      TData = FindAnimeByIdQuery,
      TError = unknown
    >(
      variables?: FindAnimeByIdQueryVariables,
      options?: Omit<UseQueryOptions<FindAnimeByIdQuery, TError, TData>, 'queryKey'> & { queryKey?: UseQueryOptions<FindAnimeByIdQuery, TError, TData>['queryKey'] }
    ) => {

    return useQuery<FindAnimeByIdQuery, TError, TData>(
      {
    queryKey: variables === undefined ? ['findAnimeById'] : ['findAnimeById', variables],
    queryFn: useFetchGraphQLData<FindAnimeByIdQuery, FindAnimeByIdQueryVariables>(FindAnimeByIdDocument).bind(null, variables),
    ...options
  }
    )};

Testing it out

Let's do a quick setup for Clerk following the Quickstart Guide. You will have all the code in the Repo so don't worry.

And also add the QueryClientProvider from React Query

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  const queryClient = new QueryClient()

  return (
    <ClerkProvider>
      <QueryClientProvider client={queryClient}>
        <html lang="en">
          <body className={inter.className}>{children}</body>
        </html>
      </QueryClientProvider>
    </ClerkProvider>
  );
}

Now we can create a dummy page app/test-codegen/page.tsx to test our generated hook

"use client"
import { useFindAnimeByIdQuery } from "@/graphql/__generated__/graphql";

export default function TestCodegen() {
  const { data, isLoading } = useFindAnimeByIdQuery({ id: 15125 });

  if (isLoading) {
    return <div>Loading...</div>;
  }
  return (
    <div className="h-screen flex items-center justify-center">
      <p>Check your network</p>
    </div>
  );
}

Once we load the page we get our JWT Token sent as the Bearer token!

There we have it! Now you can send your JWT Token or customize your generated requests to your GraphQL API URL.

Here is the link to the repo.

See you next time!

Clerk with Authn (PassKeys) in NextJs

Roberto Yamanaka — Mon, 11 Mar 2024 03:06:04 +0000

If you're like me, you already love using Clerk to handle security in your App.

However, one cool feature that is missing is the Authn/Passkey integration. Basically being able to login with your FaceId or Fingerprint. Which is pretty cool.

Since it is not coming soon to Clerk, I'm gonna show you how to hack a solution by yourself.

Setup a new Clerk Project

Go to your Clerk Dashboard and create a new project. I'm gonna call mine Passki (yes very creative) and select only the username for login (I'll later use this username as an unique identifier so keep this in mind).

Start a new NextJs Project

Lets go with the default settings and call my app Passki. I'll be using NextJs14 for this (currently NextJs' latest version).

What is your project named? my-app
Would you like to use TypeScript? No / Yes
Would you like to use ESLint? No / Yes
Would you like to use Tailwind CSS? No / Yes
Would you like to use `src/` directory? No / Yes
Would you like to use App Router? (recommended) No / Yes
Would you like to customize the default import alias (@/*)? No / Yes
What import alias would you like configured? @/*

Setup Clerk inside NextJs

Lets follow the steps in here to QuickStart our Clerk setup.

By now you should've done these from the QuickStart tutorial

Add your env variables
Wrap the app with your ClerkProvided
Added the middleware.ts
Added a simple <UserButton /> in your main App Page to login and logout

At the end of this blog post you can find the Repo for the project :)

Now to the fun part.

Strategize a solution

Understanding Authn

Authn is a new way of authenticating. Instead of relying on remembering your password you can login using a biometric, like your face or fingerprint.

This leads to a better User Experience since remembering passwords sucks.

How WebAuthn Works:

Frontend requests a Challenge: When you try to log in, you ask the server for a unique challenge, which is essentially a random, one-time code.
Activate Your Biometric: You then use your biometric (like a fingerprint or face scan) to respond. This action activates the private key stored securely on your device.
Private Key Signs the Challenge: The private key, unlocked by your biometric, signs this challenge, turning it into a 'signed challenge.'
Send Signed Challenge Back to the Server: Your device sends this signed challenge back to the server.
Server Verifies with Public Key: The server uses the public key, which corresponds to your private key, to verify the signed challenge. If it matches, your identity is confirmed, and you are granted access.

How to approach Authn with code

First we will setup the necessary libraries for this project.

Next, we will register our fingerprint following the 5 steps above.

Lastly, we will sign in with the registered fingerprint also following the 5 steps from above.

Lets get to it!

Setup

We'll be using the @simplewebauthn libraries for the whole project. I've tested many libraries to implement Authn and this on is very straightforward and intuitive.

Go ahead and install these

npm install @simplewebauthn/server

npm install @simplewebauthn/browser

npm install @simplewebauthn/types

We will also add our main entity PassKey. I will create a new path called /features/types.ts to save it for later use

export type PassKey = {
  credentialId: Uint8Array;
  credentialPublicKey: Uint8Array;
  counter: number;
  credentialDeviceType: string;
  credentialBackedUp: boolean;
  transports: Transport[];
  createdTs: number;
};

export type Transport =
  | 'ble'
  | 'cable'
  | 'hybrid'
  | 'internal'
  | 'nfc'
  | 'smart-card'
  | 'usb';

This PassKey Type will simplify our pipeline since it is the bridge between our logic and the @simplewebauthn package.

We will also need to add some identifier constants so that Authn knows which are our authorized initializers. Let's save them under /features/constants

"user server"

// Human-readable title for your website
export const RP_NAME = 'Passki';

// A unique identifier for your website
export const RP_ID = 'localhost';

// The URL at which registrations and authentications should occur
export const RP_ORIGIN = 'http://localhost:3000';

Lastly, this whole Authn pipeline requires us to keep track of an user's passkeys and their latest challenge (to prevent replay attacks). You would normally use a Database for that. But for the sake of this tutorial we are gonna use Clerk's inbuilt feature User's metadata.

The User's metadata allows us to save and access extra stuff from the User, which works really well for this tutorial like the PassKeys and the latest challenge.

In this case, we will use the private metadata since that can't be accessed from the frontend (only backend if you separate your environments well in NextJs).

Please note that an User's metadata is capped at 4kb, so better not abuse it haha.

Register your fingerprint

We should only allow registered users to add their fingerprint for extra security. Go ahead and add the custom Sign Up.

Create a new Sign Up page here app/sign-up/[[...sign-up]]/page.tsx and also add this env variable
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up

The page.tsx component should look something like this

import { SignUp } from "@clerk/nextjs";

export default function SignUpPage() {
  return (
    <div className="h-screen flex items-center justify-center">
      <SignUp />
    </div>
  );
}

Good. That will allow us to sign up for the first time. Now let's add a new fingerprint for a User.

Let's create a new path called /features/register/ where we can create the server functions necessary to serve our Components.

Next, create a createRegisterOptions function which will generate Registration Options (including a new Challenge) for the user to register a new PassKey. I'll save this new function in features/register/create-registration-options.ts

'use server';
import { clerkClient, currentUser } from '@clerk/nextjs/server';
import { generateRegistrationOptions } from '@simplewebauthn/server';
import { PublicKeyCredentialCreationOptionsJSON } from '@simplewebauthn/types';
import { PassKey } from '@/features/types';
import { RP_ID, RP_NAME } from '@/features/constants';

export async function createRegistrationOptions(): Promise<PublicKeyCredentialCreationOptionsJSON> {
  const user = await currentUser();
  if (!user || !user.username) {
    throw new Error('No user found');
  }
  // Generate WebAuthn registration options
  const userMetadata = user.privateMetadata;
  const userPassKeys = userMetadata.passKeys as PassKey[] || [];
  const options = await generateRegistrationOptions({
    rpName: RP_NAME,
    rpID: RP_ID,
    userID: user.id,
    userName: user.username,
    attestationType: 'none',
    authenticatorSelection: {
      residentKey: 'preferred',
      userVerification: 'preferred',
      authenticatorAttachment: 'platform',
    },
    excludeCredentials: userPassKeys.map((passKey) => ({
      id: passKey.credentialId,
      type: 'public-key',
    })),
  });

  // Update the latest challenge to prevent replay attacks
  await clerkClient.users.updateUserMetadata(user.id, {
    privateMetadata:{
      ...userMetadata,
      latestPassKeyChallenge: options.challenge,
    }
  });
  return options
}

With those registerOptions, our frontend Component will begin the process to register a new Passkey. It will then call the startRegistration function and send it to validate to our endRegistration function. Let's also add the endRegistrationfunction.

'use server';

import { verifyRegistrationResponse } from '@simplewebauthn/server';
import { RP_ID, RP_ORIGIN } from '@/features/constants';
import { RegistrationResponseJSON } from '@simplewebauthn/types';
import { PassKey } from '../types';
import { clerkClient, currentUser } from '@clerk/nextjs';

export async function endRegistration(registrationResponseJSON: RegistrationResponseJSON) {
    const user = await currentUser();
    const userMetadata = user?.privateMetadata
    if (!user || !userMetadata) {
      throw new Error('No user found');
    }
    const expectedChallenge = userMetadata.latestPassKeyChallenge as string || ''
    try {
      const verification = await verifyRegistrationResponse({
        response: registrationResponseJSON,
        expectedChallenge,
        expectedOrigin: RP_ORIGIN,
        expectedRPID: RP_ID,
      });
      const { verified, registrationInfo } = verification;
      if (verified && registrationInfo) {
        console.log('Registration verified');
        const {
          credentialPublicKey,
          credentialID,
          counter,
          credentialBackedUp,
        } = registrationInfo;
        const foundTransports = registrationResponseJSON.response.transports;
        const newPassKey:PassKey = {
          credentialId: credentialID,
          credentialPublicKey: credentialPublicKey,
          counter,
          credentialDeviceType: 'singleDevice',
          credentialBackedUp,
          transports: foundTransports || [],
            createdTs: Date.now(),
        }
        // Save the new pass key to the user's private metadata
        const userPassKeys = userMetadata.passKeys as PassKey[] || [];
        await clerkClient.users.updateUserMetadata(user.id, {
          privateMetadata:{
            ...userMetadata,
            passKeys: [...userPassKeys, newPassKey],
          }
        });
        return true;
      } else {
        return false;
      }
    } catch (error) {
      console.error(error);
      return false;
    }
  }

Let's create a new page called app/register-pass-key/page.tsx where we will first call the createRegistrationOptions function, then startRegistration and lastly call the endRegistrationfunction.

Here is a pretty Component using some Tailwind for that.

"use client";
import { useCallback } from "react";
import { createRegistrationOptions } from "@/features/register/create-registration-options";
import { startRegistration } from "@simplewebauthn/browser";
import { endRegistration } from "@/features/register/end-registration";

export default function RegisterPassKey() {
  const onClick = useCallback(async () => {
    const registrationOptions = await createRegistrationOptions();
    console.log("registrationOptions", registrationOptions);
    try {
      const registrationResponse = await startRegistration(registrationOptions);
      console.log("registrationResponse", registrationResponse);
      const registrationStatus = await endRegistration(registrationResponse);
      console.log("Registration successful", registrationStatus);
    } catch (error: unknown) {
      alert("Error: Authenticator was probably already registered by user");
      console.error("Error starting registration:", error);
      return;
    }
  }, []);

  return (
    <div className="relative isolate flex h-screen w-screen items-center justify-center overflow-hidden bg-gray-900">
      <div className="px-6 py-24 sm:px-6 sm:py-32 lg:px-8">
        <div className="mx-auto max-w-2xl text-center">
          <h2 className="text-4xl font-bold tracking-tight text-white sm:text-4xl">
            Setup your own Passkey
            <br />
          </h2>
          <p className="mx-auto mt-6 max-w-xl text-2xl leading-8 text-gray-300">
            You can use your fingerprint or FaceId to login to your account
          </p>
          <div className="mt-10 flex items-center justify-center gap-x-6">
            <button
              onClick={onClick}
              className="rounded-md bg-white px-3.5 py-2.5 text-sm font-semibold text-gray-900 shadow-sm hover:bg-gray-100 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-white"
            >
              Lets do it!
            </button>
          </div>
        </div>
      </div>
      <svg
        viewBox="0 0 1024 1024"
        className="absolute left-1/2 top-1/2 -z-10 h-[64rem] w-[64rem] -translate-x-1/2 [mask-image:radial-gradient(closest-side,white,transparent)]"
        aria-hidden="true"
      >
        <circle
          cx={512}
          cy={512}
          r={512}
          fill="url(#8d958450-c69f-4251-94bc-4e091a323369)"
          fillOpacity="0.7"
        />
        <defs>
          <radialGradient id="8d958450-c69f-4251-94bc-4e091a323369">
            <stop stopColor="#7775D6" />
            <stop offset={1} stopColor="#E935C1" />
          </radialGradient>
        </defs>
      </svg>
    </div>
  );
}

Right now if you sign in and go to the register-pass-keypage you should be able to add your fingerprint to your Clerk account.

If we go to our Clerk Dashboard we can see that indeed the LatestChallenge (now obsolete but still there) and the passKeysare there (only 1 for now).

Great job!

Now, this was the easy part haha. We will now turn to the second part. Actually using your fingerprint to sign in.

Authentication

Good. As we did before let's create our Sign In Component.

Add to your .env.local this env variable
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in

And create the component inside app/sign-in/[[...sign-in]]/page.tsx

"use client";
import { useState } from "react";
import { SignIn } from "@clerk/nextjs";
import SignInPassKey from "@/features/authenticate/components/signInPassKey";

export default function SignInPage() {
  const [newScreen, setNewScreen] = useState(false);

  return (
    <>
      {newScreen ? (
        <SignInPassKey />
      ) : (
        <div className="h-screen flex flex-col items-center justify-center">
          <SignIn />
          <button
            onClick={() => setNewScreen(true)}
            type="button"
            className="mt-3 rounded-md bg-blue-700 px-3.5 py-2.5 text-sm font-semibold text-white shadow-sm hover:bg-blue-900 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-blue-700"
          >
            Log in with my fingerprint ✨
          </button>
        </div>
      )}
    </>
  );
}

This Component has a child Component with our Authentication with Authn logic <SignInPassKey />. We will come back to this Component after we create the aux functions (aka the server functions).

Once again, we start by obtaining the *authentication options * to generate a New Challenge and other params.

In this case, we take the username as an input since we also need to update the user's metadata to the latest challenge (for extra security) and the username is the way we can identify the User.

Here is the code for that

'use server';
import { clerkClient } from '@clerk/nextjs/server';
import { generateAuthenticationOptions } from '@simplewebauthn/server';
import { PublicKeyCredentialRequestOptionsJSON } from '@simplewebauthn/types';
import { RP_ID } from '@/features/constants';

export async function createAuthenticationOptions(username:string): Promise<PublicKeyCredentialRequestOptionsJSON> {
  console.log('username input', username);
  if (!username) {
    throw new Error('No username provided for authentication options.');
  }
  const usernames = [username]

  const possibleUsers = await clerkClient.users.getUserList({ username:usernames });
  // A reasonable assumption since usernames should be unique
  const user = possibleUsers[0]

  // Generate WebAuthn authentication options
  const userMetadata = user.privateMetadata;
  const options = await generateAuthenticationOptions({
    rpID: RP_ID,
    userVerification: 'preferred',
  });

  // Update the latest challenge to prevent replay attacks
  await clerkClient.users.updateUserMetadata(user.id, {
    privateMetadata:{
      ...userMetadata,
      latestPassKeyChallenge: options.challenge,
    }
  });
  return options
}

With those options, the frontend Component will run the Authentication pipeline and return to our Server the Authentication Response to validate it with endAuthentication.

Here is endAuthentication

"use server";
import { clerkClient } from "@clerk/nextjs";
import {
  AuthenticationResponseJSON,
  AuthenticatorDevice,
} from "@simplewebauthn/types";
import {
  base64URLStringToUint8Array,
  findPassKeyByCredentialId,
} from "./utils";
import { verifyAuthenticationResponse } from "@simplewebauthn/server";
import { RP_ID, RP_ORIGIN } from "../constants";
import { PassKey } from "../types";
import { createSignInToken } from "./create-sign-in-token";

export async function endAuthentication(
  authenticationResponseJSON: AuthenticationResponseJSON
) {
  const { id, response } = authenticationResponseJSON;
  const { userHandle } = response; // This is the user ID
  console.log("userHandle", userHandle);
  if (!userHandle) return;
  const user = await clerkClient.users.getUser(userHandle);
  const expectedChallenge =
    (user.privateMetadata.latestPassKeyChallenge as string) || "";
  const credentialId = base64URLStringToUint8Array(id);
  const userPassKeys = (user.privateMetadata.passKeys as PassKey[]) || [];
  if (!userPassKeys) return;
  const passKey = findPassKeyByCredentialId(credentialId, userPassKeys);
  if (!passKey) return "";
  const credentialPublicKey = passKey.credentialPublicKey as Uint8Array;
  const credentialID = passKey.credentialId;
  // You may have issues with this authenticator
  // by getting "no data" make sure your types are correct.
  // That is why the extra casting
  const authenticator: AuthenticatorDevice = {
    credentialPublicKey: new Uint8Array(Object.values(credentialPublicKey)),
    credentialID: new Uint8Array(Object.values(credentialID)),
    counter: passKey.counter,
    transports: passKey.transports,
  };

  try {
    const verification = await verifyAuthenticationResponse({
      response: authenticationResponseJSON,
      expectedChallenge,
      expectedOrigin: RP_ORIGIN,
      expectedRPID: RP_ID,
      authenticator,
    });
    console.log("verification response", verification);
    if (verification.verified) {
      const newSignInToken = await createSignInToken(user.id);
      return newSignInToken;
    }
  } catch (error) {
    console.error(error);
    return;
  }
}

There are extra utils functions that help us with the parsing of Uint8's and making sure the data remains consisten accross the function.

In the end, you can see that once the Verification is Verified, we generate a Sign In Token with Clerk.

These Sign In Tokens are one time tokens to Sign In the App so they come in very handy for implementing Authn securely.

All right. now we have everything we need. Let's integrate it in the frontend Component

"use client";
import { useCallback, useState } from "react";
import { createAuthenticationOptions } from "@/features/authenticate/create-authentication-options";
import { startAuthentication } from "@simplewebauthn/browser";
import { endAuthentication } from "@/features/authenticate/end-authentication";
import { useSignIn } from "@clerk/nextjs";

export default function SignInPassKey() {
  const { signIn, setActive } = useSignIn();
  const [username, setUsername] = useState("");

  const passkeyAuthenticate = useCallback(async () => {
    const authenticationOptions = await createAuthenticationOptions(username);
    try {
      const authenticationResponse = await startAuthentication(
        authenticationOptions,
        false
      );
      console.log("authenticationResponse", authenticationResponse);
      const signInToken = await endAuthentication(authenticationResponse);
      console.log("sign in token", signInToken);
      if (!signIn || !signInToken) return;
      const res = await signIn.create({
        strategy: "ticket",
        ticket: signInToken as string,
      });
      console.log("auth response", res);
      setActive({
        session: res.createdSessionId,
      });
    } catch (error: unknown) {
      console.error("Error starting authentication:", error);
      return;
    }
  }, [username, setActive, signIn]);

  return (
    <div className="h-screen flex flex-col items-center justify-center">
      <div>
        <h2 className="text-4xl font-bold tracking-tight text-white sm:text-4xl">
          Log In with your PassKey
        </h2>
        <div className="justify-self-start mt-2">
          <label
            htmlFor="username"
            className="block text-sm font-medium leading-6 text-white text-2xl"
          >
            Username
          </label>
          <div className="mt-2 w-full">
            <input
              id="username"
              type="text"
              value={username}
              onChange={(e) => setUsername(e.target.value)}
              className="block w-full rounded-md border-0 py-1.5 text-gray-900 shadow-sm ring-1 ring-inset ring-gray-300 placeholder:text-gray-400 focus:ring-2 focus:ring-inset focus:ring-indigo-600 sm:text-sm sm:leading-6"
            />
          </div>
          <button
            type="button"
            onClick={passkeyAuthenticate}
            className="mt-3 rounded-md  w-full bg-blue-700 px-3.5 py-2.5 text-sm font-semibold text-white shadow-sm hover:bg-blue-900 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-blue-700"
          >
            Log in with my fingerprint ✨
          </button>
        </div>
      </div>
    </div>
  );
}

And there you have it! Lets try it out!

We go to the PassKey section

We choose our PassKey

And we Sign In!!!

And just like that. We are signed in with our Fingerprint

Next up

This was a lot of work. But we made it possible :)

If you have any comments or doubts, I'd be happy to discuss them on X with you.

Thanks for reading. In the next post I'll show you how to setup Clerk Phone SignUp in Expo React Native. It will be fun.

Until next time!
Roberto

Github Repo

Clerk JWT Authentication with NestJs + Passport for REST & GraphQL

Roberto Yamanaka — Wed, 18 Oct 2023 23:20:30 +0000

If you're like me. You already love using Clerk to handle all Authentication for you in the Frontend.

However, I recently needed to connect my NextJs+Clerk frontend with a NestJs backend. The docs do a good job explaining how to implement a Manual JWT Verification for the backend endpoints. But I couldn't find specific info on how to implement it with NestJs.

Here is the solution I made using PassportJs

Get your Clerk Secret Keys

To connect our NestJs application with Clerk, we'll need the and the JWT public key from the Api Keys section

Copy and save the JWT public key without the "/.well-known/jwks.json" part.

We will need it to validate the JWT coming from the frontend.

NestJs basic setup

Let's create a new Nestjs project.

$ nest new clerk-w-nest

I'm gonna go ahead and choose npm but u can choose any you like.

REST endpoint

Now let's create some rest endpoints.

$ nest g resource rest-endpoints

Let's go ahead and create a new endpoint called pingOne under our Controller Class.

// src/rest-endpoints/rest-endpoints.controller.ts
import { Controller, Get, Param } from '@nestjs/common';
import { RestEndpointsService } from './rest-endpoints.service';

@Controller('rest-endpoints')
export class RestEndpointsController {
  constructor(private readonly restEndpointsService: RestEndpointsService) {}

  @Get(':id')
  pingOne(@Param('id') id: string) {
    return this.restEndpointsService.pingOne(id);
  }
}

And modify our Service Class.

// src/rest-endpoints/rest-endpoints.service.ts
import { Injectable } from '@nestjs/common';

@Injectable()
export class RestEndpointsService {
  pingOne(id: string) {
    return `REST Ping #${id}!`;
  }
}

Now lets test the endpoint

Start the server npm run start:dev

And test it

$ curl http://localhost:3000/rest-endpoints/12345
REST Ping #12345!

Good! Now let's do the GraphQL Endpoint

GraphQL Endpoint

$ nest g resource graphql-endpoints

You'll also have to install these to use NestJs with GraphQL per the official documentation.

npm i @nestjs/graphql @nestjs/apollo @apollo/server graphql

And add this line to your ./app.module.ts

// src/app.module.ts
import { Module } from '@nestjs/common';
import { ApolloDriver } from '@nestjs/apollo';
import { RestEndpointsModule } from './rest-endpoints/rest-endpoints.module';
import { GraphqlEndpointsModule } from './graphql-endpoints/graphql-endpoints.module';
import { GraphQLModule } from '@nestjs/graphql';

@Module({
  imports: [
    GraphQLModule.forRoot({ autoSchemaFile: true, driver: ApolloDriver }),
    RestEndpointsModule,
    GraphqlEndpointsModule,
  ],
  controllers: [],
  providers: [],
})
export class AppModule {}

And now let's repeat the process from rest-endpoints

For your Resolver Class

// src/graphql-endpoints/graphql-endpoints.resolver.ts
import { Resolver, Query, Args } from '@nestjs/graphql';
import { GraphqlEndpointsService } from './graphql-endpoints.service';
import { GraphqlEndpoint } from './entities/graphql-endpoint.entity';

@Resolver(() => GraphqlEndpoint)
export class GraphqlEndpointsResolver {
  constructor(
    private readonly graphqlEndpointsService: GraphqlEndpointsService,
  ) {}

  @Query(() => String, { name: 'pingOne' })
  pingOne(@Args('id') id: string) {
    return this.graphqlEndpointsService.pingOne(id);
  }
}

For your Service Class

// src/graphql-endpoints/graphql-endpoints.service.ts
import { Injectable } from '@nestjs/common';

@Injectable()
export class GraphqlEndpointsService {
  pingOne(id: number) {
    return `GraphQL Ping #${id}!`;
  }
}

Now lets go to http://localhost:3000/graphql and test it

Good! Now to the interesting part

Creating Passport Auth Module

Let's start by creating a Nest Module for the Authentication

nest generate module authentication

Setting up Passport

Passport helps us setup our desired Authentication Strategy. We'll use the JSON Web Token (JWT) Passport Strategy to connect it with Clerk.

$ npm i passport @nestjs/passport passport-jwt jwks-rsa

The @nestjs/passport module helps us wrap this Strategy for NestJs.

To implement the Passport Strategy, first add the JWT issuer Url we copied from our Clerk Dashboard Api Keys section to our .env file.

Next you'll need to install @nestjs/config to access the env variable.

$ npm install @nestjs/config

Lets update our App module to use the .env file.

// src/app.module.ts
import { Module } from '@nestjs/common';
import { ApolloDriver } from '@nestjs/apollo';
import { RestEndpointsModule } from './rest-endpoints/rest-endpoints.module';
import { GraphqlEndpointsModule } from './graphql-endpoints/graphql-endpoints.module';
import { GraphQLModule } from '@nestjs/graphql';
import { AuthenticationModule } from './authentication/authentication.module';
import { ConfigModule } from '@nestjs/config';

@Module({
  imports: [
    ConfigModule.forRoot({
      envFilePath: [`.env`],
      isGlobal: true,
    }),
    GraphQLModule.forRoot({ autoSchemaFile: true, driver: ApolloDriver }),
    RestEndpointsModule,
    GraphqlEndpointsModule,
    AuthenticationModule,
  ],
  controllers: [],
  providers: [],
})
export class AppModule {}

And now we can create our Passport Strategy

// src/authentication/jwt.strategy.ts
import { Injectable } from '@nestjs/common';
import { PassportStrategy } from '@nestjs/passport';
import { ExtractJwt, Strategy } from 'passport-jwt';
import { passportJwtSecret } from 'jwks-rsa';
import * as dotenv from 'dotenv';
import { ConfigService } from '@nestjs/config';

dotenv.config();

@Injectable()
export class JwtStrategy extends PassportStrategy(Strategy) {
  constructor(private configService: ConfigService) {
    super({
      secretOrKeyProvider: passportJwtSecret({
        cache: true,
        rateLimit: true,
        jwksRequestsPerMinute: 5,
        jwksUri: `${configService.get(
          'CLERK_ISSUER_URL',
        )}/.well-known/jwks.json`,
      }),

      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
      issuer: `${configService.get('CLERK_ISSUER_URL')}`,
      algorithms: ['RS256'],
    });
    console.log('JwtStrategy initialized');
  }

  validate(payload: unknown): unknown {
    // This one is really useful to check the jwt payload!
    // console.log('Validating payload:', payload);
    return payload;
  }
}

In NestJS, to make a Passport Strategy, you simply extend the class you get from the PassportStrategy function, which comes from @nestjs/passport. You tell it which strategy you're using by giving it the JWT Strategy from passport-jwt.

You pass the config for the strategy in the constructor via super(). This setup ensures we can decode JWT tokens and sets the API to recognize tokens with the RS256 sign.

RS256 is chosen because it's a widely-accepted RSA signature-based algorithm that provides strong security by using a private key for signing and a public key for verification, ensuring the JWT wasn't altered after its creation.

NestJS replaces the usual verify callback with a validate() method. But here's the cool part: Clerk does the hard part of authenticating the user. By the time validate() is called, Clerk already knows who the user is and gives you their details in the payload. Your app then attaches this to the request, so you can use it anywhere, like in controllers or middleware.

The next step is to create our custom Authentication Guard that extends from Passport's AuthGuard.

// src/authentication/jwt-auth.guard.ts
import { ExecutionContext, Injectable } from '@nestjs/common';
import { AuthGuard } from '@nestjs/passport';
import { GqlExecutionContext } from '@nestjs/graphql';

@Injectable()
export class JwtAuthGuard extends AuthGuard('jwt') {
  getRequest(context: ExecutionContext) {
    const ctx = GqlExecutionContext.create(context);
    return ctx.getContext().req;
  }
}

The JwtAuthGuard is a custom guard tailored for both REST and GraphQL in a NestJS application. It extends the default AuthGuard and specifies the 'jwt' strategy. The getRequest method part helps integrate the guard with GraphQL. When invoked, it takes the current ExecutionContext, converts it to a GraphQL-specific context using GqlExecutionContext.create, and then extracts and returns the request (req) object. This ensures that our JWT authentication works seamlessly across both RESTful routes and GraphQL queries or mutations.

Lastly lets update our Authentication Module

// src/authentication/authentication.module.ts
import { Module } from '@nestjs/common';
import { JwtStrategy } from './jwt.strategy';
import { JwtAuthGuard } from './jwt-auth.guard';

@Module({
  providers: [JwtStrategy, JwtAuthGuard],
})
export class AuthenticationModule {}

Good! We are done. Now lets add our custom guards to our endpoints to test them out.

In our src/rest-endpoints/rest-endpoints.controller.ts we add the guard to our ping endpoint.

// src/rest-endpoints/rest-endpoints.controller.ts
import { Controller, Get, Param, UseGuards } from '@nestjs/common';
import { RestEndpointsService } from './rest-endpoints.service';
import { JwtAuthGuard } from 'src/authentication/jwt-auth.guard';

@Controller('rest-endpoints')
export class RestEndpointsController {
  constructor(private readonly restEndpointsService: RestEndpointsService) {}

  @UseGuards(JwtAuthGuard) // This extra line
  @Get(':id')
  pingOne(@Param('id') id: string) {
    return this.restEndpointsService.pingOne(id);
  }
}

And that's it! If we run

$ curl http://localhost:3000/rest-endpoints/12345

We'll get a

{"message":"Unauthorized","statusCode":401}

But when we add a Bearer Token from Clerk

$ curl -H "Authorization: Bearer <CLERK_BEARER_TOKEN_HERE>" http://localhost:3000/rest-endpoints/12345

We get

REST Ping #12345!

If we try it out with our GraphQL Endpoint

// src/graphql-endpoints/graphql-endpoints.resolver.ts
import { Resolver, Query, Args } from '@nestjs/graphql';
import { GraphqlEndpointsService } from './graphql-endpoints.service';
import { GraphqlEndpoint } from './entities/graphql-endpoint.entity';
import { UseGuards } from '@nestjs/common';
import { JwtAuthGuard } from 'src/authentication/jwt-auth.guard';

@Resolver(() => GraphqlEndpoint)
export class GraphqlEndpointsResolver {
  constructor(
    private readonly graphqlEndpointsService: GraphqlEndpointsService,
  ) {}

  @UseGuards(JwtAuthGuard)
  @Query(() => String, { name: 'pingOne' })
  pingOne(@Args('id') id: string) {
    return this.graphqlEndpointsService.pingOne(id);
  }
}

We get the expected behaviour!

And that's it! Hope this was useful. I'll be posting more about Clerk and NestJs in the coming weeks so if ur into that follow me on Twitter
https://twitter.com/RobertoYamanaka

NOTE: Getting a Bearer Token from Clerk

You can find your Clerk Bearer token under localstorage in your frontend as clerk-db-jwt

Github Repo

https://github.com/robertoyamanaka/clerk-w-nestjs