DEV Community: Hanko.io

How to add Passkey Login to your React App

Ashutosh Bhadauriya — Tue, 12 Mar 2024 14:26:47 +0000

Passkey authentication is gaining popularity faster than ever before. You must have probably noticed a new 'Sign in with a Passkey' option when logging into places like Github or the Apple Store by now.

With Passkeys, your users can sign in without needing any passwords at all. Instead, it uses Touch ID or Face ID on their device to authenticate them, which makes it way more secure and easier to use than old-school passwords or even the two-factor authentication methods we're used to. On top of that, it provides a super smooth login experience too.

In this tutorial, we'll show you how you can add Passkey login for your users to your React Application using Hanko Passkey API. While we're using Express.js for our backend, the process will be pretty similar if you're working with any other JavaScript or TypeScript-based backend.

We've already built a basic auth and in this guide, we'll focus specifically on how you can add a Passkey login to your existing auth system. So, no reinventing the wheel here; instead, we'll show you how to integrate Passkeys seamlessly with your existing authentication flow. Check out our demo app repo here.

Let's get to building.

Get the API key and Tenant ID from Hanko

Before everything you'll need to get the credentials from Hanko Cloud. So, after creating your account on Hanko and setting up the organization, go ahead and click on 'Create new project,' and then choose 'Passkey infrastructure' and 'Create project'.

Enter your Project name and URL and click on 'Create project'.

Copy the 'Tenant ID', then create an API key, copy the API key secret, and add it to your .env file.

After setting up your React app with an Express backend, you'll need to add environment variables copied above in the backend directory for the APIs we're going to make. The frontend will simply call the APIs to allow users to register and log in with passkeys.



PASSKEYS_API_KEY="your-passkey-api-secret"
NEXT_PUBLIC_PASSKEYS_TENANT_ID="your-tenant-id"

Install the Passkey SDK

Install the JavaScript SDK provided by Hanko and webauth-json package by GitHub. Note that, you need to install the SDK on the backend directory and webauthn-json package on the frontend directory.



npm add @teamhanko/passkeys-sdk @github/webauthn-json

Allow your users to register passkey

When it comes to passkey registration, you'll need to decide where and how your users can add passkeys to their accounts. It's entirely up to you. In our case, we've decided to provide a 'Register Passkey' button on the 'dashboard' page.

On your express backend, you’ll have to use tenant({ ... }).registration.initialize() and .registration.finalize() to create and store a passkey for your user. We'll create a /api/passkeys/register endpoint that will utilize these.

On your frontend, you’ll have to call create() from @github/webauthn-json with the object .registration.initialize() returned.

First, create two services startServerPasskeyRegistration() and finishServerPasskeyRegistration() in the /express-backend/services/passkey.js

In the startServerPasskeyRegistration() function we retrieve the user's information from a database and initiate the passkey registration process by calling the passkeyApi.registration.initialize() method with the user's ID and email. This function returns the options required for creating a new passkey on the client side. The finishServerPasskeyRegistration() function finalizes the registration process by sending the client-side credential to the passkey API.

These functions are then exported to be used in the express-backend/controllers/passkey.js .



import { tenant } from "@teamhanko/passkeys-sdk";
import dotenv from "dotenv";
import db from "../db.js";

dotenv.config();

const passkeyApi = tenant({
  apiKey: process.env.PASSKEYS_API_KEY,
  tenantId: process.env.PASSKEYS_TENANT_ID,
});

async function startServerPasskeyRegistration(userID) {
  const user = db.users.find((user) => user.id === userID);

  const createOptions = await passkeyApi.registration.initialize({
    userId: user.id,
    username: user.email || "",
  });

  return createOptions;
}

async function finishServerPasskeyRegistration(credential) {
  await passkeyApi.registration.finalize(credential);
}

export {
  startServerPasskeyRegistration,
  finishServerPasskeyRegistration,
};

Now we definehandlePasskeyRegister() controller that handles two stages of the passkey registration process: initiation and completion. The function utilizes the helper functions startServerPasskeyRegistration() and finishServerPasskeyRegistration() we created above.



import {
  startServerPasskeyRegistration,
  finishServerPasskeyRegistration,
} from "../service/passkey.js";

async function handlePasskeyRegister(req, res) {
  const { user } = req;
  const userID = user.id;

  if (!userID) {
    return res.status(401).json({ message: "Unauthorized" });
  }
  console.log("userId", userID);

  const { start, finish, credential } = req.body;

  try {
    if (start) {
      const createOptions = await startServerPasskeyRegistration(userID);
      return res.json({ createOptions });
    }
    if (finish) {
      await finishServerPasskeyRegistration(credential);
      return res.json({ message: "Registered Passkey" });
    }
  } catch (error) {
    return res.status(500).json(error);
  }
}

export { handlePasskeyRegister, handlePasskeyLogin };

Now, you can use it in the specific route, here we do it in the /api/passkeys/register endpoint.



import express from "express";
const router = express.Router();
import { handlePasskeyRegister, handlePasskeyLogin } from "../controllers/passkey.js";
import { checkAuth } from "../middleware/auth.js";

router.post("/passkeys/register", checkAuth, handlePasskeyRegister);

export default router;

The backend part is done, now it's time to add the 'Register Passkey' button on the frontend.

Here, the registerPasskey() function handles the passkey registration process. It first sends a request to the server to initiate the registration process and receives the response for creating a new passkey. It then uses the @github/webauthn-json library to create a new passkey credential based on the received options from the response. Finally, it sends another request to the server with the newly created credential to complete the registration process.



import {
    create,
    type CredentialCreationOptionsJSON,
} from "@github/webauthn-json";
import { useNavigate } from "react-router-dom";

import { Button } from "@/components/ui/button";
import { toast } from "sonner"



const Dashboard = () => {

    // your code..

    async function registerPasskey() {
        const createOptionsResponse = await fetch("http://localhost:5001/api/passkeys/register", {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            credentials: 'include',
            body: JSON.stringify({ start: true, finish: false, credential: null }),
        });

        const { createOptions } = await createOptionsResponse.json();
        console.log("createOptions", createOptions)

        const credential = await create(
            createOptions as CredentialCreationOptionsJSON,
        );
        console.log(credential)

        const response = await fetch("http://localhost:5001/api/passkeys/register", {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            credentials: "include",
            body: JSON.stringify({ start: false, finish: true, credential }),
        });
        console.log(response)

        if (response.ok) {
            toast.success("Registered passkey successfully!");
            return;
        }
    }
    return (
        <div className="p-4">
                <Button
                    onClick={() => registerPasskey()}
                    className="flex justify-center items-center space-x-2 mt-8"
                >
                    Register a new passkey
                </Button>
        </div>
    )
}

export default Dashboard;

With all the necessary things in place, you should now be able to register passkeys successfully.

Allow your users to log in with Passkey

Implementing the login flow will be very similar to the Passkey Registration flow. Inside of /express-backend/services/passkey.js create two more functions startServerPasskeyLogin() and finishServerPasskeyLogin().



async function startServerPasskeyLogin() {
  const options = await passkeyApi.login.initialize();
  return options;
}

async function finishServerPasskeyLogin(options) {
  const response = await passkeyApi.login.finalize(options);
  return response;
}

Now, similar to passkey registration create a handlePasskeyLogin() controller. Here, after the passkey login process is finished, the finishServerPasskeyLogin() returns JWT, which we decode using jose to get the User ID, verify it against the database and create a new session for the user.



async function handlePasskeyLogin(req, res) {
  const { start, finish, options } = req.body;

  try {
    if (start) {
      const loginOptions = await startServerPasskeyLogin();
      return res.json({ loginOptions });
    }
    if (finish) {
      const jwtToken = await finishServerPasskeyLogin(options);
      const userID = await getUserID(jwtToken?.token ?? "");
      console.log("userID from hanko", userID);
      const user = db.users.find((user) => user.id === userID);
      if (!user) {
        return res.status(401).json({ message: "Invalid user" });
      }
      console.log("user", user);
      const sessionId = uuidv4();
      res.cookie("sessionId", sessionId);
      return res.json({ message: " Passkey Login successful" });
    }
  } catch (error) {
    console.error(error);
    return res
      .status(500)
      .json({ message: "An error occurred during the passke login process." });
  }
}

Now you can use this controller in the api/passkeys/login route.



import express from "express";
const router = express.Router();
import { handlePasskeyRegister, handlePasskeyLogin } from "../controllers/passkey.js";
import { checkAuth } from "../middleware/auth.js";


router.post("/passkeys/register", checkAuth, handlePasskeyRegister);
router.post("/passkeys/login", handlePasskeyLogin);

export default router;

Alright, now we just need to create a 'Sign in with a Passkey' button on the frontend and use the endpoints we created above.



import { Button } from "@/components/ui/button";
import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
import { Input } from "@/components/ui/input";
import { Label } from "@/components/ui/label";
import useLogin from "@/hooks/useLogin";
import { useState } from "react";
import { useNavigate } from "react-router-dom";
import { get } from "@github/webauthn-json";

const Login = () => {
    const navigate = useNavigate();

    const { loginUser } = useLogin();
    const [email, setEmail] = useState('');
    const [password, setPassword] = useState('');


    const handleSubmit = async (event: React.FormEvent<HTMLFormElement>) => {
        event.preventDefault();
        const success = await loginUser(email, password);
        if (success) {
            navigate('/dashboard');
        }
    };

    // the signInWithPasskey function takes care of logging in the user with passkey
    async function signInWithPasskey() {
        const createOptionsResponse = await fetch("http://localhost:5001/api/passkeys/login", {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            credentials: 'include',
            body: JSON.stringify({ start: true, finish: false, credential: null }),
        });

        const { loginOptions } = await createOptionsResponse.json();

        // Open "register passkey" dialog
        const options = await get(
            loginOptions as any,
        );

        const response = await fetch("http://localhost:5001/api/passkeys/login", {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            credentials: 'include',
            body: JSON.stringify({ start: false, finish: true, options }),
        });

        if (response.ok) {
            console.log("user logged in with passkey")
            navigate("/dashboard")
            return;
        }
    }
    return (
        <div className="w-screen h-screen flex items-center justify-center">
            <Card className="w-full max-w-lg">
                <CardHeader>
                    <CardTitle>Sign In</CardTitle>
                    <CardDescription className="">Choose your preferred sign in method</CardDescription>
                </CardHeader>
                <CardContent>
                    <div className="flex flex-col">
                        <form onSubmit={handleSubmit}>
                            <div className="flex flex-col gap-y-2">
                                <Label>Email</Label>
                                <Input
                                    id="email"
                                    required
                                    name="email"
                                    type="email"
                                    value={email}
                                    onChange={(e) => setEmail(e.target.value)}
                                    autoComplete="email"
                                />
                                <Label>Password</Label>
                                <Input
                                    id="password"
                                    name="password"
                                    type="password"
                                    value={password}
                                    onChange={(e) => setPassword(e.target.value)}
                                    autoComplete="current-password"
                                />
                            </div>
                            <Button type="submit" className="mt-4 w-full">Sign in with Email</Button>
                        </form>
                        <div className="relative mt-4">
                            <div className="absolute inset-0 flex items-center">
                                <span className="w-full border-t" />
                            </div>
                            <div className="relative flex justify-center text-xs uppercase">
                                <span className="bg-background px-2 text-muted-foreground">
                                    Or continue with
                                </span>
                            </div>
                        </div>
                        <Button className="mt-4 w-full" onClick={() => signInWithPasskey()}>Sign in with a Passkey</Button>
                    </div>
                </CardContent>
            </Card>
        </div>
    )
}

export default Login;

Alright, now head over to the login page and try logging in with your passkey 🚀 Check out the application repo here.

Don't hesitate to reach out to us on Discord, if you get into any issues.

Adding passkeys to a Remix App

Ashutosh Bhadauriya — Mon, 04 Mar 2024 10:45:53 +0000

This tutorial will show how you can add passkeys to your Remix app using Hanko. We have a basic auth already setup, that uses email and password to login user. You can follow this awesome guide by Matt Stobbs to see how we have added authentication.

Typically, to add passkeys to any app, you'd need two things:

a backend to handle the authentication flow and store data about your user's passkeys
a couple of functions on your frontend to bring up & handle the "Sign in with passkey" dialog

Let's dive in and see how you will do this.

Get the API key and Tenant ID from Hanko

After creating your account on Hanko and setting up the organization, go ahead and select 'Create new project,' and then choose 'Passkey infrastructure' and 'Create project'.

Provide the Project name and URL and click on 'Create project'. Remember, if you're working on the project locally, the url will be of localhost, for example, http://localhost:3000 .

Copy the 'Tenant ID', create an API key and copy the secret, and add it to your .env file.

PASSKEYS_API_KEY="your-passkey-api-secret"
PASSKEYS_TENANT_ID="your-tenant-id"

Install Hanko Passkey SDK

Install the JavaScript SDK provided by Hanko and webauth-json package by GitHub.

npm add @teamhanko/passkeys-sdk @github/webauthn-json

Allow your users to register passkey

Your users will need to add passkeys to their account. It’s up to you how and where you let them do this. We do it in the app/routes/dashboard.tsx route.

On your backend, you’ll have to call tenant({ ... }).registration.initialize() and .registration.finalize() to create and store a passkey for your user.

On your frontend, you’ll have to call create() from @github/webauthn-json with the object .registration.initialize() returned.

create() will return a PublicKeyCredential object, which you’ll have to pass to .registration.finalize().

Here, we create two functions startServerPasskeyRegistration which uses registration.initialize() endpoint and finishServerPasskeyRegistration which uses registration.finalize() endpoint.

import { tenant } from "@teamhanko/passkeys-sdk";
import { db } from "~/db";

const passkeyApi = tenant({
  apiKey: process.env.PASSKEYS_API_KEY!,
  tenantId: process.env.PASSKEYS_TENANT_ID!,
});

export async function startServerPasskeyRegistration(userID: string) {
  const user = db.users.find((user) => user.id === userID);

  const createOptions = await passkeyApi.registration.initialize({
    userId: user!.id,
    username: user!.email || "",
  });

  return createOptions;
}

export async function finishServerPasskeyRegistration(credential: any) {
  await passkeyApi.registration.finalize(credential);
}

Inside of routes/api.passkeys.register.tsx create a route action using the functions created above. This action will be responsible for registering the passkey for the user.

import { json } from "@remix-run/node";
import { finishServerPasskeyRegistration, startServerPasskeyRegistration } from "~/utils/passkey.server";
import { getSession } from "~/utils/session.server";


export const action = async ({ request }: { request: Request }) => {

    const sessionData = await getSession(request);
    const userID = sessionData.get("userId");

    if (!userID) {
        return json({ message: "Unauthorized" }, 401);
    }
    const { start, finish, credential } = await request.json();

    try {
        if (start) {
            const createOptions = await startServerPasskeyRegistration(userID);
            return json({ createOptions });
        }
        if (finish) {
            await finishServerPasskeyRegistration(credential);
            return json({ message: "Registered Passkey" });
        }
    } catch (error) {
        return json(error, 500);
    }
};

Now, we're done with the backend setup. Next up, let's add a "Register Passkey" button. We'll use the endpoints we set up earlier to generate and save a passkey for the user.

import { Form } from "@remix-   run/react";
import { Button } from "~/components/ui/button";
import { toast } from "sonner"

import {
    create,
    type CredentialCreationOptionsJSON,
} from "@github/webauthn-json";
import { json, LoaderFunction, redirect } from "@remix-run/node";
import { getUserId } from "~/utils/session.server";

export const loader: LoaderFunction = async ({ request }) => {
    const userId = await getUserId(request);
    console.log(userId)
    if (!userId) return redirect("/login");
    return json({});
  }

export default function DashboardPage() {
    async function registerPasskey() {
        const createOptionsResponse = await fetch("/api/passkeys/register", {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify({ start: true, finish: false, credential: null }),
        });

        const { createOptions } = await createOptionsResponse.json();

        // Open "register passkey" dialog
        const credential = await create(
            createOptions as CredentialCreationOptionsJSON,
        );

        const response = await fetch("/api/passkeys/register", {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify({ start: false, finish: true, credential }),
        });

        if (response.ok) {
            toast.success("Registered passkey successfully!");
            return;
        }
    }
    return (
        <div className="p-4">
            <Form action="/logout" method="post">
                <Button type="submit" variant="link">
                    Logout
                </Button>
            </Form>
            <div>
                <Button
                    onClick={() => registerPasskey()}
                    className="flex justify-center items-center space-x-2"
                >
                    Register a new passkey
                </Button>
            </div>
        </div>
    );
}

If everything is set up correctly, now you should be able to register the passkey.

Adding the SignIn with Passkey functionality

The process will be very similar to Passkey Registration. Inside of utils/passkey.server.ts add two more functions startServerPasskeyLogin() and finishServerPasskeyLogin() which use the login.initialize() and login.finalize() endpoints respectively.

export async function startServerPasskeyLogin() {
  const options = await passkeyApi.login.initialize();
  return options;
}

export async function finishServerPasskeyLogin(options: any) {
  const response = await passkeyApi.login.finalize(options);
  return response;
}

Now, similar to passkey registration create a route action routes/api.passkeys.login.tsx to log in the user. Here, after the login process is finished, the finishServerPasskeyLogin returns JWT, which we decode using jose to get the User ID and create a new session for the user.

import { json } from "@remix-run/node";
import { getUserID } from "~/utils/get-user-id.server";
import { finishServerPasskeyLogin, startServerPasskeyLogin } from "~/utils/passkey.server";
import { createUserSession } from "~/utils/session.server";

export const action = async ({ request }: { request: Request }) => {
    const { start, finish, options } = await request.json();

    try {
        if (start) {
            const loginOptions = await startServerPasskeyLogin();
            return json({ loginOptions });
        }
        if (finish) {
            const jwtToken = await finishServerPasskeyLogin(options);
            const userID = await getUserID(jwtToken?.token ?? '');

            return createUserSession({
                request,
                userId: userID ?? '',
            });
        }
    } catch (error) {
        if(error instanceof Response){
            return error;
        }
        return json(error, 500);
    }
};

Here's the function to extract the UserID from jose.

// app/utils/get-user-id.server.ts

import * as jose from "jose";

export async function getUserID(token: string) {
  const payload = jose.decodeJwt(token ?? "");

  const userID = payload.sub;
  return userID;
}

Alright, now we just need to create a 'SignIn with Passkey' button and use the endpoints we created above. After the response is successful, we navigate the user to /dashboard route.

import { ActionFunction } from "@remix-run/node";
import { Form, useNavigate } from "@remix-run/react";
import { Button } from "~/components/ui/button";
import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "~/components/ui/card";
import { Input } from "~/components/ui/input";
import { Label } from "~/components/ui/label";
import { createUserSession, verifyLogin } from "~/utils/session.server";
import { get } from "@github/webauthn-json";

export const action: ActionFunction = async ({ request }) => {
    const formData = await request.formData();
    const email = formData.get("email") as string;
    const password = formData.get("password") as string;

    const user = await verifyLogin(email, password);

    if (!user) {
        return new Response("Invalid email or password", {
            status: 401,
            headers: {
                "Content-Type": "text/plain",
            },
        });
    }

    return createUserSession({
        request,
        userId: user.id,
    });
}

export default function LoginPage() {
    const navigate = useNavigate();

    // here we add the 
    async function signInWithPasskey() {
        const createOptionsResponse = await fetch("/api/passkeys/login", {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify({ start: true, finish: false, credential: null }),
        });

        const { loginOptions } = await createOptionsResponse.json();

        // Open "login passkey" dialog
        const options = await get(
            loginOptions as any,
        );

        const response = await fetch("/api/passkeys/login", {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify({ start: false, finish: true, options }),
        });

        if (response.ok) {
            console.log("user logged in with passkey")
            navigate("/dashboard")
            return;
        }
    }
    return (
        <div>
            <div className="w-screen h-screen flex items-center justify-center">
                <Card className="w-full max-w-lg">
                    <CardHeader>
                        <CardTitle>Sign In</CardTitle>
                        <CardDescription className="">Choose your preferred sign in method</CardDescription>
                    </CardHeader>
                    <CardContent>
                        <div className="flex flex-col">
                            <Form method="POST">
                                <div className="flex flex-col gap-y-2">
                                    <Label>Email</Label>
                                    <Input
                                        id="email"
                                        required
                                        name="email"
                                        type="email"
                                        autoComplete="email"
                                    />
                                    <Label>Password</Label>
                                    <Input
                                        id="password"
                                        name="password"
                                        type="password"
                                        autoComplete="current-password"
                                    />
                                </div>
                                <Button type="submit" className="mt-4 w-full">Sign in with Email</Button>
                            </Form>
                            <div className="relative mt-4">
                                <div className="absolute inset-0 flex items-center">
                                    <span className="w-full border-t" />
                                </div>
                                <div className="relative flex justify-center text-xs uppercase">
                                    <span className="bg-background px-2 text-muted-foreground">
                                        Or continue with
                                    </span>
                                </div>
                            </div>
                            <Button className="mt-4 w-full" onClick={() => signInWithPasskey()}>Passkey</Button>
                        </div>
                    </CardContent>
                </Card>
            </div>
        </div>
    );
}

That's all. You have successfully integrated Passkey login to your remix app, making the authentication process much easier and smoother for your user 🚀

Check out the github repo, if you wanna play around.

teamhanko / passkeys-remix

Adding Passkey Login to Remix with Hanko

This repo shows how you can add passkey login with Hanko Passkey API to your Remix app.

Clone the repo

git clone https://github.com/teamhanko/remix-passkeys.git

Add the environment variables

Add the following environment variables to .env.local file.

PASSKEYS_API_KEY=your-hanko-passkey-api-key
PASSKEYS_TENANT_ID=your-hanko-passkey-tenant-id

Install dependencies

pnpm install

Run the project

pnpm run dev

View on GitHub

How to add Passkey Login to Next.js using NextAuth and Hanko

Ashutosh Bhadauriya — Mon, 04 Mar 2024 06:45:17 +0000

When logging in to Apple Store or GitHub, you must have seen a new 'Sign in with Passkey' button. Passkey login is a cool new way to sign in without needing any passwords. It uses Touch ID or Face ID on your device to authenticate, which makes it way more secure and easier to use than old-school passwords and even those two-factor authentication methods we're used to.

Typically, to add passkeys to any app, you'd need two things:

a backend to handle the authentication flow and store data about your user's passkeys
a couple of functions on your frontend to bring up & handle the "Sign in with passkey" dialog

If you're using Next.js, you can easily do both of these things with NextAuth and our accompanying provider @teamhanko/passkeys-next-auth-provider.

Our open-source passkey server is an API you can call from your (Next.js) backend to handle the authentication flow (and storing all relevant data about your user's passkeys).

@teamhanko/passkeys-next-auth-provider is a NextAuth provider that calls this API for you, and lets you bring up the "Sign in with passkey" with a single function call.

@github/webauthn-json is an optional package that makes it easier to work with the WebAuthn API on your frontend.

The tech stack we'll use.

Next.js 14
NextAuth for adding auth
Resend for sending magic links for auth
Supabase as our DB
Shadcn UI for pretty UI out of the box

We have already configured everything and in this tutorial, we'll be just showing how you can add Passkey login. Let’s get to building. You can either follow the video or go through the guide.

Add Passkey Login to Next.js using NextAuth and Hanko - YouTube

In this video we show you how fast and easy it is to add Passkey login to Next.js app using NextAuth thanks to the Hanko Passkeys API

youtube.com

We'll be using NextAuth for authentication and passkey provider for NextAuth by Hanko to add passkey login functionality. After initializing your Next.js and configuring NextAuth you'll need to get the Hanko API key secret and Tenant ID. Navigate over to Hanko Cloud to grab those.

Get the API key and Tenant ID from Hanko

After creating your account on Hanko and setting up the organization, go ahead and select 'Create new project,' and then choose 'Passkey infrastructure' and 'Create project'.

Provide your Project name and URL and click on 'Create project'.

Copy the 'Tenant ID', create an API key, and add it to your .env file.

PASSKEYS_API_KEY="your-passkey-api-secret"
NEXT_PUBLIC_PASSKEYS_TENANT_ID="your-tenant-id"

Install the NextAuth Passkey provider

Install the passkey provider for NextAuth from Hanko and webauthn-json package by GitHub.

pnpm add @teamhanko/passkeys-next-auth-provider @github/webauthn-json

Add the Passkey provider to NextAuth

PasskeyProvider({
      tenant: tenant({
        apiKey: process.env.PASSKEYS_API_KEY!,
        tenantId: process.env.NEXT_PUBLIC_PASSKEYS_TENANT_ID!,
      }),
      async authorize({ userId }) {
        const user = await prisma.user.findUnique({ where: { id: userId } });
        if (!user) return null;
        return user;
      },
    }),

As we're using Prisma Adapter by NextAuth, we'll need to also to use session: { strategy: "jwt" } and modify the session to get id from token.sub. This is how the complete code for auth.ts the file looks after adding Hanko passkey provider.

Note that, if you don't plan to use any adapters, you just need to add the Passkey provider and don't modify anything.

import type { NextAuthOptions } from "next-auth";
import GitHubProvider from "next-auth/providers/github";
import EmailProvider from "next-auth/providers/email";
import { PrismaAdapter } from "@auth/prisma-adapter";
import {
  tenant,
  PasskeyProvider,
} from "@teamhanko/passkeys-next-auth-provider";

import prisma from "./db";

export const authOptions = {
  providers: [
    GitHubProvider({
      clientId: process.env.GITHUB_ID!,
      clientSecret: process.env.GITHUB_SECRET_ID!,
      allowDangerousEmailAccountLinking: true,
    }),
    EmailProvider({
      server: {
        host: process.env.EMAIL_SERVER_HOST,
        port: process.env.EMAIL_SERVER_PORT,
        auth: {
          user: process.env.EMAIL_SERVER_USER,
          pass: process.env.EMAIL_SERVER_PASSWORD,
        },
      },
      from: process.env.EMAIL_FROM,
    }),
    PasskeyProvider({
      tenant: tenant({
        apiKey: process.env.PASSKEYS_API_KEY!,
        tenantId: process.env.NEXT_PUBLIC_PASSKEYS_TENANT_ID!,
      }),
      async authorize({ userId }) {
        const user = await prisma.user.findUnique({ where: { id: userId } });
        if (!user) return null;
        return user;
      },
    }),
  ],
  adapter: PrismaAdapter(prisma),
  session: { strategy: "jwt" },
  callbacks: {
    session: ({ session, token }) => {
      if (token) {
        return {
          ...session,
          user: {
            ...session.user,
            id: token.sub,
          },
        };
      } else {
        return session;
      }
    },
  },
} satisfies NextAuthOptions;

Allow your users to register passkey as a login method

Your users will have to add passkeys to their account somehow. It’s up to you how and where you let them do this, but typically this would be a button on an “Account Settings” page.

On your backend, you’ll have to call tenant({ ... }).registration.initialize() and .registration.finalize() to create and store a passkey for your user.

On your frontend, you’ll have to call create() from @github/webauthn-json with the object .registration.initialize() returned.

create() will return a PublicKeyCredential object, which you’ll have to pass to .registration.finalize().

Here we have created a new file named passkey.ts, inside of the server directory.

"use server"

import { getServerSession } from "next-auth";
import { tenant } from "@teamhanko/passkeys-next-auth-provider";
import prisma from "./db";
import { authOptions } from "./auth";

const passkeyApi = tenant({
    apiKey: process.env.PASSKEYS_API_KEY!,
    tenantId: process.env.NEXT_PUBLIC_PASSKEYS_TENANT_ID!,
});

export async function startServerPasskeyRegistration() {
    const session = await getServerSession(authOptions);
    const sessionUser = session?.user;

    const user = await prisma.user.findUnique({
        where: { email: sessionUser?.email as string },
        select: { id: true, name: true },
    });

    const createOptions = await passkeyApi.registration.initialize({
        userId: user!.id,
        username: user!.name || "",
    });

    return createOptions;
}

export async function finishServerPasskeyRegistration(credential: any) {
    const session = await getServerSession(authOptions);
    if (!session) throw new Error("Not logged in");

    await passkeyApi.registration.finalize(credential);
}

Alright, now let's get to creating a 'Passkey register' button. This is what kicks off the whole Passkey registration process for that user account.

"use client"

import { finishServerPasskeyRegistration, startServerPasskeyRegistration } from '@/lib/passkey';
import { Button } from './ui/button';
import Passkey from './icons/passkey';
import {
    create,
    type CredentialCreationOptionsJSON,
} from "@github/webauthn-json";

const RegisterNewPasskey = () => {
    async function registerPasskey() {
        const createOptions = await startServerPasskeyRegistration();
        const credential = await create(createOptions as CredentialCreationOptionsJSON);
        await finishServerPasskeyRegistration(credential);
    }
    return (
        <Button
            onClick={() => registerPasskey()}
            className="flex justify-center items-center space-x-2"
        >
            <Passkey className="w-4 h-4 mr-2" />
            Register a new passkey
        </Button>
    )
}

export default RegisterNewPasskey

Add a button to allow your users to log in with a passkey

Now that the passkey is successfully registered, let's add a 'Sign in with Passkey' button. This will allow users to easily login using their passkey.

"use client"

import Passkey from "./icons/passkey";
import { Button } from "./ui/button";
import { signInWithPasskey } from "@teamhanko/passkeys-next-auth-provider/client";

const SignInWithPasskey = () => {
    return (
        <Button onClick={() => signInWithPasskey({ tenantId: process.env.NEXT_PUBLIC_PASSKEYS_TENANT_ID!, callbackUrl: `${window.location.origin}/dashboard/settings` })} className="mt-4" variant="secondary"> <Passkey className="w-4 h-4 mr-2" /> Passkey </Button>
    )
}

export default SignInWithPasskey

And that's it! You now have a working Passkey login, making the authentication process much easier for your users 🚀

If you want to take a closer look or try it out for yourself, feel free to check out our GitHub repo.

teamhanko / passkeys-next-auth-starter

Hanko Passkey Starter for Next-Auth

This repo shows how you can add passkey login with Hanko Passkey API to your Next.js app that uses Next-Auth for authentication.

Technologies used

Clone the repo

git clone https://github.com/teamhanko/passkeys-next-auth-starter.git

Add the environment variables

Add the following environment variables to .env.local file.

NEXTAUTH_SECRET=random-string
NEXTAUTH_URL=http://localhost:3000

GITHUB_ID=
GITHUB_SECRET_ID=

# for email service
EMAIL_SERVER_USER=resend
EMAIL_SERVER_PASSWORD=your-resend-api-key
EMAIL_SERVER_HOST=smtp.resend.com
EMAIL_SERVER_PORT=465
EMAIL_FROM=onboarding@resend.dev

DATABASE_URL=your-db-url

PASSKEYS_API_KEY=your-hanko-passkey-api-key
NEXT_PUBLIC_PASSKEYS_TENANT_ID=your-hanko-passkey-tenant-id

Install dependencies

pnpm install

Run the project

pnpm run dev

View on GitHub

✨ Make Hanko Components Shine 💫

Esther-Lita — Mon, 16 Oct 2023 09:15:24 +0000

TL;DR

In this tutorial, we will customize the Hanko Web Components, drawing inspiration from the following themes:

Google
Barbie
GitHub
Cal.com
Instagram
Spooky Season

Hanko Components

Hanko is an easiest-to-use authentication solution that provides two web components: the Hanko-Auth, dedicated to streamlining the user authentication process, and the Hanko-Profile, where users can manage their account information. We know how important first impressions are, so we want to show you how to customize the components from Hanko to flash your users with a shiny user interface.

⭐️⭐️⭐️ https://github.com/teamhanko/hanko ⭐️⭐️⭐️

ℹ️ Before we start with the styling process we suggest you to take a look at the guide on how to implement the components in your project, click here.

Custom CSS Variables 🎨

Using CSS variables is one of our recommended approaches to style the hanko-auth and hanko-profile components. You can take a look at the list of CSS variables and the default values.

CSS Variables
When the Hanko Web Components were created, a selection of properties (CSS Custom Variables) was chosen to rule the design and harmony of the elements inside them. By changing the default value of the specific custom variable all the elements that are styled with the same variable will be updated.

Google Style

Hanko-Auth component:

Hanko-Profile component, renaming passkey:

You can get the Google inspired UI by changing the value of the following CSS variables in your styles:

:root {
  --color: #424c55;
  --color-shade-1: #d6d6d6;
  --brand-color: #568aed;
  --background-color: #ffffff;
  --border-radius: 4px;
  --font-size: 14px;
  --item-height: 44px;
  --headline1-font-size: 28px;
  --headline1-font-weight: 450;
  --container-padding: 40px;
  --container-max-width: 410px;
}

hanko-profile {
  --container-padding: 20px;
  --container-max-width: 600px;
}

CSS Shadow Parts

The use of Shadow Parts is also recommended to style the hanko-auth and hanko-profile components. You can add customization to a specific element inside the components utilizing the ::part selector. The default behavior of the Hanko Web Components is to be attached to the Shadow DOM, which is useful for preventing styles from leaking out of components and applying to other elements. Here is the list of the shadow parts that you can use to style the Hanko Web Components.

CSS Shadow Parts
When the Hanko Web Components were created, a part was added inside some elements by assigning a part attribute to the element. Similar to a class selector in CSS (class="hanko_container"), a part is specified in the HTML element (part="container"). Then the element can be styled using the root name and the ::part selector (hanko-auth::part(container){ background: black; }).

Barbie Style 👱🏻‍♀️

Hanko-Auth component:

Hanko-Profile component:

You can get the Barbie inspired UI by targeting and styling the following ::part selectors in your styles:

hanko-auth::part(container),
hanko-profile::part(container) {
  max-width: 550px;
  padding: 50px 30px;
  border: solid 1px #dd9dbf;
  border-radius: 60px;
}

hanko-profile::part(form-item) {
  background-color: #fceff6;
}

hanko-auth::part(divider-line) {
  border-color: #dc9ebe;
}

hanko-auth::part(headline1),
hanko-profile::part(headline1),
hanko-auth::part(headline2),
hanko-profile::part(headline2),
hanko-auth::part(divider-text),
hanko-auth::part(secondary-button) {
  color: #e0218a;
}

hanko-auth::part(headline1),
hanko-profile::part(headline1),
hanko-auth::part(headline2),
hanko-profile::part(headline2) {
  font-family: "Galada", cursive;
}

hanko-auth::part(input),
hanko-profile::part(input) {
  border-radius: 20px;
  border-color: #dc9ebe;
}

hanko-auth::part(input)::placeholder,
hanko-profile::part(input)::placeholder {
  color: #f2a2ae;
}

hanko-auth::part(button),
hanko-profile::part(button) {
  border-color: #e0218a;
  border-radius: 20px;
}

hanko-auth::part(primary-button),
hanko-profile::part(primary-button) {
  background-color: #e0218a;
}

hanko-auth::part(secondary-button) {
  color: #d8038d;
}

hanko-profile::part(paragraph) {
  color: #dc9ebe;
  font-family: "IBM Plex Serif", serif;
}

Combining CSS Variables & Shadow Parts

The best way to achieve amazing results is by combining both suggested approach. Changing the values of the CSS Variables and using the ::part selectors to style the elements is the best way to transform the components at a deeper level.

GitHub Style

Hanko-Auth component:

Hanko-Profile component, adding a secondary email address:

You can apply the following styles to get the GitHub inspired UI:

:root {
  --color-shade-1: #d0d7dd;
  --brand-color: #1b7f36;
  --background-color: #f5f8fa;
  --headline1-font-size: 24px;
  --headline1-font-weight: 300;
  --headline1-margin: 10px 40px;
  --border-radius: 6px;
  --font-size: 14px;
  --item-height: 32px;
  --font-weight: 500;
  --link-color: #0969da;
  --divider-padding: 0 20px;
}

hanko-auth {
  --container-max-width: 320px;
  --container-padding: 16px;
  --color: #0969da;
}

hanko-profile {
  --container-max-width: 550px;
  --container-padding: 30px;
  --color: #1f2328;
}

hanko-auth::part(container),
hanko-profile::part(container) {
  border: solid 1px #d8dee3;
  border-radius: 6px;
}

hanko-auth::part(headline1),
hanko-profile::part(headline1) {
  color: #1f2328;
}

hanko-auth::part(input),
hanko-profile::part(input) {
  background-color: #ffffff;
}

hanko-auth::part(secondary-button) {
  border: none;
  margin: 0 0 0 20px;
}

hanko-auth::part(divider-text) {
  color: #1f2328;
}

Cal.com

Hanko-Auth component:

Hanko-Profile component:

You can apply the following styles to get the Cal.com inspired UI:

:root {
  --color: #111827;
  --color-shade-1: #d1d5db;
  --brand-color: #111827;
  --background-color: #ffffff;
  --headline1-font-size: 29px;
  --headline2-font-size: 16px;
  --headline1-margin: 10px 40px;
  --border-radius: 6px;
  --font-size: 14px;
  --item-height: 36px;
  --link-color: #1c73e8;
  --divider-padding: 0 15px;
}

hanko-auth {
  --container-max-width: 640px;
  --container-padding: 40px;
}

hanko-profile {
  --container-max-width: 550px;
  --container-padding: 30px;
}

hanko-auth::part(container),
hanko-profile::part(container) {
  border: solid 1px #d8dee3;
  border-radius: 6px;
}

hanko-auth::part(headline1),
hanko-profile::part(headline1),
hanko-auth::part(headline2),
hanko-profile::part(headline2) {
  color: #1f2328;
  line-height: 36px;
  font-family: Cal Sans;
}

hanko-auth::part(form-item) {
  min-width: 100%;
}

hanko-auth::part(input),
hanko-profile::part(input) {
  background-color: #ffffff;
  margin-bottom: 12px;
}

hanko-auth::part(secondary-button) {
  border-color: var(--color-shade-1);
}

hanko-auth::part(divider) {
  margin: 24px 0;
}

Customization through CSS Classes

This last approach is not recommended by the Hanko team. In order to use this approach, the web components must not be attached to the shadow DOM. You need to manually detach the web components from the Shadow DOM when you register the component:

register("https://hanko.yourdomain.com", { shadow: false });

You can use this CSS example file as a reference. To change a specific property you need to override the predefined ones, as shown below:

.hanko_container {
  background-color: blue !important;
}

Or you can bring all the styles from scratch by also preventing injecting styles on the component and modifying the value of the CSS classes:

register("https://hanko.yourdomain.com", {
  shadow: false,
  injectStyles: false,
});

This last approach will be tested by styling the following inspired themes, removing all the default styles and bringing our own. We will use the CSS custom classes provided by Hanko to target and style the elements.

Instagram Style

Hanko-Auth component:

Hanko-Profile component:

You can see the code for this themed UI here

Spooky Style

Hanko-Auth component:

Hanko-Profile component:

You can see the code for this themed UI here

If you want us to keep creating this type of content for you, please don't forget to leave a star on GitHub for the team!

⭐️⭐️⭐️ https://github.com/teamhanko/hanko ⭐️⭐️⭐️

💥 Building a Next.js 13 Todo app with Prisma and passkey login 🤯

Esther-Lita — Wed, 13 Sep 2023 14:11:24 +0000

In this tutorial, you’ll learn how to build a Todo app with the Next.js 13 popular “App Router” structure and understand some of the most important changes that come with it.

We will build a fully functional Todo app:

Create todo
Check and delete a single item
Delete all todos

We will use Hanko for:

Login and registration
User management
Logout

Prisma will handle the storage.

Where should we start? 👷🏻‍♂️

Dealing with complicated frameworks can steal the joy from the beautiful process of creating something from scratch, that’s why finding the right stack for our project is a big step. In this guide, I’ve decided to bring Next.js as the main character of this project because of the amazing opportunity to test the crazy twist they brought with all these “use server” vs “use client” implementations. Also when you are creating the new app, Next.js makes it very simple by giving you the option to integrate everything you’ll probably need like Typescript, ESLint and Tailwind CSS, and yes, we’ll use them all!

Tailwind CSS

For most of the project, I will use Tailwind CSS to style, because I just find it super easy to implement and to bring life into the app, when it comes to code maintenance it’s easy to read and immediately know what is going on in the exact element and Tailwind just makes working with CSS enjoyable.

Prisma

In this app, we don’t need a lot when it comes to where we will store the data, and Prisma is just perfect for what we need for the “todos” to be properly created, updated, and/or deleted.

Hanko

When it comes to securing an app the first thing that comes into play is the combination of building, configuring and styling the login and sign-up on the frontend, and then the complexity of the backend with the functionality, authentication, handling errors, and all the details needed to have a successful and secure “user session”. Here is where Hanko enters the game, taking care of the login, registration, user management and logout, giving us the freedom to be able to spend more time and focus on the other parts of the project.

“Build the best login you have ever seen”

Hanko is an open-source authentication solution focused on taking the development experience to a new level. You can decide what type of information your app will require for the login like email & password, passkeys, email passcodes, and 3rd-party identity providers. Then you can be as creative as you like by styling Hanko's Web Components.

We are ready to set it 🆙

Here I'll walk you through creating the project setup for the application. Make sure to have the latest version of Node.js installed.

Create a new Next.js app

To create a new Next.js app, we can use the create-next-app or create-next-app@latest command-line tool followed by the name of your choice for the app. Open your terminal in Visual Studio Code and run the following command:

 npx  create-next-app@latest todo-nextjs-hanko

This will start the process of creating the project, you will then be asked some prompts on what you will use for the app. The project configuration options should look something like:

The above choices will create a new Next.js app with the chosen name, all the required dependencies for this project will also be installed.

Understanding the project structure

When using version 13 of Next.js, we have the option to work with the App Router directory instead of the Pages Router, for a quick summary we could say that:

The new directory named “app” is replacing “pages”
“page.tsx|page.jsx” is the new “index.tsx|index.jsx”
“layout.tsx” is the new “_app.tsx”
Everything is a Server Component unless you make it a Client Component using the “use client” directive at the top of the file.
API Routes are now Server Components or Route Handlers

Remove unnecessary files, such as logos, icons, etc. If you are going to use Tailwind CSS make sure to bring your desired configuration to the tailwind.config.ts file, defining your color palette, fonts, breakpoints, etc.

ℹ️ For more information about the App Router of Next.js click here.

Get Prisma started

Install the Prisma CLI as a development dependency in the project:

 npm install prisma --save-dev

Set up Prisma with the init command of the Prisma CLI:

 npx prisma init --datasource-provider sqlite

This creates a new prisma directory with your Prisma schema file and configures SQLite as your database. Once we also create the "Todo" model, the Prisma schema file should look like this:

// This is your Prisma schema file,
// learn more about it in the docs: https://pris.ly/d/prisma-schema

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "sqlite"
  url      = env("DATABASE_URL")
}

model Todo {

 id String @id @default(uuid())
  title String
  complete Boolean
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

At this point, you have a Prisma schema but no database yet. Run the following command in your terminal to create the SQLite database and the Todo table:

 $ npx prisma migrate dev --name init

This command did two things:

It creates a new SQL migration file for this migration in the prisma/migrations directory.
It runs the SQL migration file against the database.

Because the SQLite database file didn't exist before, the command also created it inside the prisma directory with the name dev.db as defined via the environment variable in the .env file.

To prevent problems when instantiating PrismaClient, on the Prisma Docs there’s a section dedicated to the best practice to do it. Let’s try it by creating a db.ts file in the root of the app and add the following code inside:

import { PrismaClient } from "@prisma/client";

const globalForPrisma = globalThis as unknown as {
  prisma: PrismaClient | undefined;
};

export const prisma = globalForPrisma.prisma ?? new PrismaClient();

if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = prisma;

ℹ️ For more information about Prisma integration click here.

Building the user interface 🛠️

Keeping in mind that we want to build a simple "todo app" with a nice login to protect the todos, we will only need two pages:

The login page where the Hanko-auth component will play its part in handling authentication.
The todo page where all the todos will be displayed.

App structure

In the App Router directory, the page.tsx is like the new index.tsx, which means that this name will play an important role when creating a new route. You can define a page by exporting a component from a page.tsx file.

Now you can update the page.tsx file to display "Hello World" as done below.

export default function Home() {
  return (
    <div>
      <p>Hello World</p>
    </div>
  );
}

We will get back to it later to add a nice login with Hanko.

The Todo page

We will style this page using Tailwind CSS classes to simply create a centered container to display the todos. We need a form with an input to create the new todos, and every todo element will have a checkbox and a delete button. Inside the app directory, create a new todo folder with a page.tsx file inside of it. Use the code below as the todo/page.tsx contents:

export default function Todo() {
  return (
    <main className=" flex min-h-screen justify-center items-center bg-slate-50 ">
      <div className="bg-slate-300 rounded-3xl py-6  h-[400px] w-[450px] flex flex-col text-slate-800">
        <h1 className="text-3xl text-center">My to dos</h1>
        <div className="mx-8 mt-4 mb-6">
          <form className="flex gap-3 items-center">
            <input
              type="text"
              name="title"
              placeholder="New todo"
              className=" border border-slate-400 rounded-full flex-1  py-1 px-2 outline-none focus-within:border-slate-100 bg-slate-50 focus-within:bg-slate-100 placeholder:text-slate-300"
              required
            />
            <button className="  bg-slate-50 rounded-full p-1 border border-slate-400 text-slate-400 hover:text-slate-500 text-base hover:ring-0 hover:ring-slate-100 hover:border-slate-500">
              <p className=" text-center">
             +
              </p>
            </button>
          </form>
        </div>
        <ul className="px-6">
          <li className="flex px-4">
            <span className="flex gap-2 flex-1">
              <input
                type="checkbox"
                name="check"
                className="peer cursor-pointer accent-slate-300 "
              />
              <label
                htmlFor=""
                className="peer-checked:line-through peer-checked:text-slate-500 cursor-pointer"
              >
                Todo 1
              </label>
            </span>
            <button className="text-slate-500  hover:text-slate-800 mr-3">
              X
            </button>
          </li>
        </ul>
      </div>
    </main>
  );
}

🚨 For a better UI use SVGs or icons inside the buttons.

ℹ️ For a better understanding of the Tailwind CSS classes click here.

Todos in the making 🚧

To make our app functional, we need to be able to create a new todo, then check the todo once it’s completed and finally be able to remove a single todo from the list.

API Routes in Next.js 13

When using the App Router of Next.js 13, the API Routes are replaced by Route Handlers and they are defined in a route.ts|js file inside the app directory. There cannot be a route file at the same route segment level as a page.tsx. Read more about the Route Handlers in the Next.js Docs.

Inside the app directory create an api folder. We will group our Route Handlers as follows: one directory todo with a route.ts which will contain the POST HTTP method handler for creating a new todo, and in that same directory we will use a dynamic route to GET and DELETE todos. Should look like the following example:

api
└── todo
    ├── [id]
    │   └── route.ts
    └── route.ts

New Todo

Let’s start by creating a todo. This is a good moment to start breaking it down into components, let’s first create a components folder at the root directory, then create a components/todos/NewTodo.tsx file and use the following as its contents:

"use client";
import { useState } from "react";
import { useRouter } from "next/navigation";

export const NewTodo = () => {
  const [newItem, setNewItem] = useState("");

  const router = useRouter();
  const create = async (e: React.SyntheticEvent) => {
    e.preventDefault();
    await fetch(`/api/todo`, {
      method: "POST",
      credentials: "include",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        title: newItem,
      }),
    });

    router.refresh();
    setNewItem("");
  };
  return (
    <div className="mx-8 mt-4 mb-6">
      <form onSubmit={create} className="flex gap-3 items-center">
        <input
          type="text"
          name="title"
          value={newItem}
          onChange={(e) => setNewItem(e.target.value)}
          placeholder="New todo"
          className=" border border-slate-400 rounded-full flex-1  py-1 px-2 outline-none focus-within:border-slate-100 bg-slate-50 focus-within:bg-slate-100 placeholder:text-slate-300"
          required
        />
        <button
          type="submit"
          className="  bg-slate-50 rounded-full p-1 border border-slate-400 text-slate-400 hover:text-slate-500 text-base hover:ring-0 hover:ring-slate-100 hover:border-slate-500"
        >
          <p className=" text-center">+</p>
        </button>
      </form>
    </div>
  );
}

This is a good example of where to bring the "use client" directive to the game, since we are using useState() and subscribing to interactive events.

This is how we call Prisma to create the todo inside the api/todo/route.ts Route Handler:

import { NextResponse } from "next/server";
import { prisma } from "@/db";

export async function POST(req: Request) {
  const { title } = await req.json();

  await prisma.todo.create({
    data: { title, complete: false },
  });

  return NextResponse.json({ message: "Created Todo" }, { status: 200 });
}

You can decide how to check for the right values to be passed and how to handle the errors in the Route Handlers.

Let’s test the "all server components" until we say the opposite from Next.js 13 by calling Prisma from the todo/page.tsx file to get all our todos, then we pass them to our components/todos/TodoItem.tsx file to be displayed. This is how the todo/page.tsx should look after our changes:

import { NewTodo } from "@/components/todos/NewTodo";
import { TodoItem } from "@/components/todos/TodoItem";
import { prisma } from "@/db";

export default async function Todo() {
  const todos = await prisma.todo.findMany();

  return (
    <main className=" flex min-h-screen justify-center items-center bg-slate-50 ">
      <div className="bg-slate-300 rounded-3xl py-6  h-[400px] w-[450px] flex flex-col text-slate-800">
        <h1 className="text-3xl text-center">My to dos</h1>
        <NewTodo />
        <ul className="px-6">
        <TodoItem  todos={todos} />
        </ul>
      </div>
    </main>
  );
}

🚨 Client Components themselves cannot be async functions (official FAQ). And Prisma will break the app if you try to call it inside a Client Component.

Update and Delete todo by ID ✅

Now we already have a way to create a new todo and to display the list of all the todos, in the next step we need a way to handle marking a todo as completed and to handle the deletion of a todo. Accordingly, we create update and delete functions that fetch our dynamic route. This would be the components/todos/TodoItem.tsx file:

"use client";
import { useRouter } from "next/navigation";
import { Todo } from "@prisma/client";

export const TodoItem = ({ todos }: { todos: Todo[] }) => {
  const router = useRouter();
  const update = async (todo: Todo) => {
    await fetch(`/api/todo/${todo.id}`, {
      method: "PATCH",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        completed: !todo.complete,
      }),
    });
    router.refresh();
  };

  const deleteTodo = async (todo: Todo) => {
    await fetch(`/api/todo/${todo.id}`, {
      method: "DELETE",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        id: todo.id,
      }),
    });

    router.refresh();
  };
  return (
    <>
      {todos.map((todo) => {
        return (
          <li key={todo.id} className="flex px-4">
            <span className="flex gap-2 flex-1">
              <input
                type="checkbox"
                name="check"
                checked={todo.complete}
                onChange={() => update(todo)}
                className="peer cursor-pointer accent-slate-300 "
              />
              <label
                htmlFor={todo.id}
                className="peer-checked:line-through peer-checked:text-slate-500 cursor-pointer"
              >
                {todo.title}
              </label>
            </span>
            <button
              onClick={() => deleteTodo(todo)}
              className="text-slate-500  hover:text-slate-800 mr-3"
            >
              X
            </button>
          </li>
        );
      })}
    </>
  );
};

Add the following code inside the api/todo/[id]/route.ts Route Handler:

import { NextResponse } from "next/server";
import { prisma } from "@/db";

export async function PATCH(
  req: Request,
  { params: { id } }: { params: { id: string } }
) {
  const { completed } = await req.json();

  await prisma.todo.update({
    where: {
      id: id,
    },
    data: {
      complete: completed,
    },
  });
  return NextResponse.json({ message: "Updated" }, { status: 200 });
}

export async function DELETE(req: Request) {
  const { id } = await req.json();

  await prisma.todo.delete({
    where: {
      id: id,
    },
  });
  return NextResponse.json({ message: "Deleted Item" }, { status: 200 });
}

ℹ️ For more information on the Prisma Client Api click here.

Authentication by Hanko

By now you should have a fully functional todo app running. We should start working on the security.

If you’re familiar with Hanko you can skip the next step, otherwise keep on reading to get started with Hanko Cloud to get your Hanko API running.

Hanko Cloud setup ☁️

Visit Hanko Cloud and create an account. Then create an organization for your Hanko project.

Then create a new project and set the App URL to your development URL (example: http://localhost:3000):

And that’s all! Now you can always return to your Hanko Cloud dashboard to see your API URL and other insights about your project, you can also change the app URL in the settings, so that once you want to move from "development" to "production", you can change it to a proper domain/URL. Take the time to discover all the features.

Adding Hanko to the Next.js app

Hanko is a lightweight and easy to implement user authentication solution that makes the transition to passkeys a lot simpler. Let’s bring Hanko to the game by installing the package running the code below:

npm install @teamhanko/hanko-elements

First, let’s update our "Home" page and rename the function to "Login". Import the register function from @teamhanko/hanko-elements, and call the function with the Hanko API URL as an argument to register the <hanko-auth>. Now include it in your JSX:

"use client";
import { useEffect} from "react";
import { register } from "@teamhanko/hanko-elements";

const hankoApi = "YOUR_HANKO_API_URL";
export default function Login() {
  useEffect(() => {
    //
    register(hankoApi ?? "").catch((error) => {
      console.log(error);
    });
  }, []);

  return (
    <div className="flex min-h-screen justify-center items-center ">
      <hanko-auth />
    </div>
  );
}

The code snippet above should display the Hanko authentication component:

The <hanko-profile> component offers a page for managing email addresses and passkeys, and we want to get access to it. Let's create a profile button component by creating a file components/Profile.tsx and use the following code as its content:

"use client";
import { useEffect, useState } from "react";
import { register } from "@teamhanko/hanko-elements";

const hankoApi = "YOUR_HANKO_API_URL";

export const Profile = () => {
  const [openState, setOpenState] = useState(false);

  useEffect(() => {
    register(hankoApi ?? "").catch((error) => {
      console.log(error);
    });
  }, []);

  const openProfile = () => {
    setOpenState(!openState);
  };

  return (
    <>
      <button type="button" onClick={openProfile}>
        Profile
      </button>
      {openState && (
        <div className=" absolute top-14 ">
          <section className=" w-[450px] h-auto rounded-2xl bg-white p-5">
            <hanko-profile />
          </section>
        </div>
      )}
    </>
  );
};

It should look like this:

Now let’s use @teamhanko/hanko-elements to manage user logouts by creating a logout button component. Create a file components/Logout.tsx and use the following as its content:

"use client";
import { useState, useEffect, useCallback } from "react";
import { useRouter } from "next/navigation";
import { Hanko } from "@teamhanko/hanko-elements";

const hankoApi = "YOUR_HANKO_API_URL";

export const Logout = () => {
  const router = useRouter();
  const [hanko, setHanko] = useState<Hanko>();

  useEffect(() => {
    import("@teamhanko/hanko-elements").then(({ Hanko }) =>
      setHanko(new Hanko(hankoApi ?? ""))
    );
  }, []);

  const logout = () => {
    hanko?.user
      .logout()
      .then(() => {
        router.push("/");
        router.refresh();
        return;
      })
      .catch((error) => {
        console.log(error);
      });
  };
  return (
    <>
      <button type="button" onClick={logout}>Logout</button>
    </>
  );
};

When a user logs out, a specific event is triggered that you can subscribe to, like redirecting to an specific page after logout:

  const renewSession = useCallback(() => {
    router.replace("/");
  }, [router]);

  useEffect(
    () =>
      hanko?.onSessionExpired(() => {
        renewSession();
      }),

    [hanko, renewSession]
  );

We will use both buttons at the top left of our Todo page.

ℹ️For more information about all the events that you can "listen" from the Hanko client click here.

Customizing Hanko Components

Hanko components are very easy to customize! To change the <hanko-auth > component, inside our globals.css file we can change the default values of the preconfigured CSS variables listed here to change the default color for the primary button and the border-radius for example:

:root {
  --border-radius: 20px;
  --brand-color: #ff2e4c;
  --brand-color-shade-1: #d52845;
  --brand-color-shade-2: #d62a4c;
}

ℹ️ For more information on how to customize Hanko Components click here.

Verifying JWT with jose library

The JWT is signed by Hanko and to secure our app we still need to verify the JWT.

What are JWTs?
A JSON Web Token (JWT) is a compact and self-contained way for transmitting information between parties as a JSON object in a secure way. The purpose of a JWT is to ensure the authenticity of the data.

Hanko handles the authentication and signing of the JWT. On successful authentication with Hanko a cookie, which contains said JWT as its value, is set. We don’t really need to know a lot about them but it’s worth getting familiar with the parts of a JWT (header, payload and signature), and what a JWKS is. For more information you can also visit JWT.io.

To verify the JWT we need to install the jose-jwt package:

npm i jose

Jose is a JavaScript module that supports JWT and provides functionality for signing and verifying tokens.

ℹ️ For more information about Jose click here.

Middleware

Create a new file middleware.tsx in the root of your project and use the following code:

import * as jose from "jose";
import { NextRequest, NextResponse } from "next/server";

const hankoApi = "YOUR_HANKO_API_URL";

export default async function middleware(req: NextRequest) {
  const token = req.cookies.get("hanko")?.value;

  const JWKS = jose.createRemoteJWKSet(
    new URL(`${hankoApi}/.well-known/jwks.json`)
  );

  try {
    const verifiedJWT = await jose.jwtVerify(token, JWKS);
    console.log(verifiedJWT);
  } catch {
return NextResponse.redirect(new URL("/", req.url));
}
}

To verify the JWT we need the token and the JWKS. We get the token from the "hanko" cookie, and then we obtain the JSON Web Key Set (JWKS) by calling the createRemoteJWKSet function from jose. Then we call await jose.jwtVerify(token, JWKS). If the token can be verified, then the promise returned from the function resolves to a decoded token. If it cannot be verified, then the promise rejects and we can catch the error and handle it appropriately, e.g. by redirecting the user to the login/home page. If you console.log the const verifiedJWT you should see the decoded token showing the payload, the protectedHeader and the key. Inside the key, you should be able to see a "true" if it’s verified.

ℹ️ For more information about Next.js Middleware click here.

Securing the application and redirecting 🔐

We want to prevent unauthorized users from getting access to private user data. A simple way to do this is by adding the paths to be protected in the Middleware configuration. Copy the following code at the bottom of your middleware.tsx file:

export const config = {
  matcher: ["/todo"],
};

Update the Login page to subscribe to the events of the Hanko client and redirect to the Todo page after a successful login:

"use client";
import { useEffect, useState, useCallback } from "react";
import { useRouter } from "next/navigation";
import { register, Hanko } from "@teamhanko/hanko-elements";

const hankoApi = "YOUR_HANKO_API_URL";
export default function Login() {
  const router = useRouter();
  const [hanko, setHanko] = useState<Hanko>();

  useEffect(() => {
    import("@teamhanko/hanko-elements").then(({ Hanko }) =>
      setHanko(new Hanko(hankoApi ?? ""))
    );
  }, []);

  const redirectAfterLogin = useCallback(() => {
    router.replace("/todo");
  }, [router]);

  useEffect(
    () =>
      hanko?.onAuthFlowCompleted(() => {
        redirectAfterLogin();
      }),
    [hanko, redirectAfterLogin]
  );

  useEffect(() => {
    //
    register(hankoApi ?? "").catch((error) => {
      console.log(error);
    });
  }, []);

  return (
    <div className="flex min-h-screen justify-center items-center bg-slate-50">
      <div className="bg-white p-5 rounded-2xl shadow-md">
        <hanko-auth />
      </div>
    </div>
  );
}

Time to display the right Todos 🪄✨

Lastly, we should only display the todos for the user that is logged in. To do so, we need to link the todos to the correct "user ID". The first step is to update the Todo model in the prisma schema:

model Todo {
  userId String
  id String @id @default(uuid())
  title String
  complete Boolean
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

Then run the following command to create a migration:

npx prisma migrate

Or the following to push the schema changes directly to the database:

npx prisma db push

Next step is to update the api/todo/route.ts file to get the user ID from the token, then create a new todo if there is a user ID:

import { NextResponse } from "next/server";
import { cookies } from "next/headers";
import * as jose from "jose";
import { prisma } from "@/db";

export async function userId() {
  const token = cookies().get("hanko")?.value;
  const payload = jose.decodeJwt(token ?? "");

  return payload.sub;
}

export async function POST(req: Request) {
  const userID = await userId();
  const { title } = await req.json();

  if (userID) {
    if (typeof title !== "string" || title.length === 0) {
      throw new Error("That can't be a title");
    }
    await prisma.todo.create({
      data: { title, complete: false, userId: userID ?? "" },
    });

    return NextResponse.json({ message: "Created Todo" }, { status: 200 });
  } else {
    return NextResponse.json({ error: "Not Found" }, { status: 404 });
  }
}

The final step is to update the Prisma call to fetch all the todos from the todo/page.tsx:

import { Logout } from "@/components/Logout";
import { Profile } from "@/components/Profile";
import { NewTodo } from "@/components/todos/NewTodo";
import { TodoItem } from "@/components/todos/TodoItem";
import { prisma } from "@/db";
import { userId } from "../api/todo/route";

export default async function Todo() {
  const userID = await userId();

  const todos = await prisma.todo.findMany({
    where: {
      userId: { equals: userID },
    },
  });

  return (
    <main className=" flex flex-col min-h-screen justify-center items-center bg-slate-50 relative ">
      <div className="absolute top-4 left-16">
        <div className=" relative py-4 space-x-6">
          <Profile />
          <Logout />
        </div>
      </div>
      <div className="bg-slate-300 rounded-3xl py-6  h-[400px] w-[450px] flex flex-col text-slate-800">
        <h1 className="text-3xl text-center">My to dos</h1>
        <NewTodo />
        <ul className="px-6">
          <TodoItem todos={todos} />
        </ul>
      </div>
    </main>
  );
}

🤩 App demonstration

You made it! 🎉

Congratulations, You now have a fully functional "Todo App"!

Thanks for staying all the way to the end, today you’ve learnt how to implement some of the Next.js new features, how to authenticate users with Hanko, and a little bit about databases with Prisma.

Next.js App Router has surely been a challenge for me, the transition to learn when and how to use some of the new features can take time but from my perspective it’s totally worth the try.

In times of constant changes, being able to count on authentication easy to integrate is almost a dream come true, Hanko aims to change the way developers and users experience both sides of the login.

Thank you for reading, auf wiedersehen! 👋

Send Hanko auth emails from your domain via Resend

Ashutosh Bhadauriya — Mon, 04 Sep 2023 12:37:45 +0000

Hanko has made it incredibly simple to add authentication to your application and get started quickly. However, you may have noticed, currently, all emails are sent from mail@hankocloud.com

While this works perfectly initially, as your product grows, you might wanna send emails through your custom domain to enhance brand visibility and have full control over your emails. Hanko makes it super easy for you to do that through your custom SMTP server.

We'll be using the SMTP server provided by Resend for this purpose. Resend is a modern tool that makes it super easy to send and manage transactional emails. Additionally, it will enable you to monitor all your Hanko authentication emails and verify if they were actually sent.

So, let's get started.

Head over to Resend and create an account if you haven't yet. Navigate to Domains section in the right sidebar, click on 'Add domain', and add your domain and region.

Now you'll need to create an API key. Go to the API Keys section, click on 'Create API Key', and fill in the required details.

Navigate to resend SMTP page, you'll see all the details of your SMTP server here. You'll need to copy-paste these to Hanko.

Next, go to your Hanko project and navigate to 'Settings' in the sidebar. Click on 'SMTP' there and fill in the details.

Copy the host, port, and username from resend. Next, in the 'Password' section, enter the API key you got from Resend. In the 'Sender email address' section, put the email address you'll be sending emails from, and then hit 'Save'.

And there you go! Your emails are now ready to be sent from your custom domain 🎉

Check the Resend docs to know more about it.

Passkeys for native iOS app authentication

Jan Gerle — Mon, 19 Jul 2021 21:09:55 +0000

In this second part of our passkeys series, we will be modifying Apple's Shiny iOS app to make use of the same passkeys (a.k.a. WebAuthn credentials) that we created with our web app from part one.

So far we saw that the passkeys are automatically synced between your Apple devices and you could use them in Safari with the web app. Now it is time to make them accessible in native iOS apps as well.

Remember: This will allow you to register to a website with Touch ID in Safari, then download the app on your iPhone, and sign in to that app again with Touch ID or Face ID without using a password at all. It also works the other way around, of course.

What are passkeys again, you ask? It's a brand new technology for secure passwordless authentication introduced by Apple at WWDC21.

A word of warning: We were pretty excited when we heard that Apple finally supports platform-wide WebAuthn on iOS. So when we started to work on the app we quickly found out that Apple's APIs are still a bit... beta. We ran into some WebAuthn-related bugs and had to create an "experimental" version of our Authentication API to work around them.

Please activate the experimental features in the Hanko Authentication API. To accomplish this, log into your Hanko Console, select the Relying Party, and navigate to the "General Settings". On the right side you will find the button to activate the experimental features.

We have created bug reports at Apple and provided them with the details. It seems like other developers have encountered these errors as well, so we assume that Apple will fix them sooner or later.

Prerequisites

Running the web app on HTTPS

We assume that you have the web app from part one up and running on your own HTTPS-capable host with a valid certificate. Use Let's Encrypt for a start. Otherwise the mobile app integration will fail due to the required Associated Domains capability.

Associated domains establish a secure association between domains and your app so you can share credentials or provide features in your app from your website.

-- Apple Developer documentation

Apple Developer account

The Associated Domains capability is only available to you if you are on a paid Apple Developer plan. As a team member you need access to the Developer Resources.

Xcode 13 (Beta)

You need Xcode 13 to work on this project and enjoy beautiful APIs like "ASAuthorizationPlatformPublicKeyCredentialRegistration" 👀.

iOS or iPadOS 15 (Dev Beta)

To make use of the new Keychain-sync feature you need a device with iOS or iPadOS 15 which is currently available at Apple's Developer Beta program.

This device needs to be configured in Xcode, obviously.

iCloud needs to be set up with the same Apple ID as on your Mac! Otherwise there will be no syncing...

Reminder: Enable Platform Authenticator Syncing on your Apple devices

In iOS 15, turn on the Syncing Platform Authenticator switch under Settings > Developer. The Developer menu is available on your device when you set it up as a development device in Xcode.

In macOS Monterey, go to Safari > Preferences, click the Advanced tab, and select the “Show Develop menu in menu bar” option. Then enable the Develop > Enable Syncing Platform Authenticator menu item in Safari.

Getting the iOS app to work

After having completed all of the above prerequisites we can proceed to configure the Shiny mobile app.

Clone the repo of our WebAuthn-enabled Shiny app from Github
Open it up in Xcode, select the Shiny Project and:
1. In the Signing & Capabilities pane choose your team from the Team drop-down menu to let Xcode automatically manage your provisioning profile.
2. Add the Associated Domains capability, and specify your domain with the webcredentials service (e.g. webcredentials:yourdomain.com).
Get your Team ID (e.g. 1ABC23DEF4) and the generated Bundle Identifier (e.g. com.example.apple-samplecode.Shiny1ABC23DEF4)
In your web app you need to setup the Apple Site Association by adding the following line to your config/config.yamlfile: iosAppId: "<Team ID>.<Bundle Identifier>", e.g. iosAppId: "1ABC23DEF4.com.example.apple-samplecode.Shiny1ABC23DEF4"
- Save the file and restart the webapp
In the mobile app in the Accountmanager file change the domain variable to your web app's domain: let domain = "yourdomain.com"
Attach your iPhone or iPad to your Mac and select it as execution environment in Xcode
In Xcode, clean the build folder and start the mobile app

The first start might take a while, but after a few seconds you should have the Shiny app running on your device. If you have created an account in the web app using your Mac, you should be presented with a sign-in dialogue, asking for Touch ID.

The source code

Basically we have taken Apple's Shiny app and taught it to sign in users with passkeys. We have removed most of the superfluous password parts, but other than that tried not to modify it too much so you can clearly see the steps needed.

The magic happens in the Shared folder, especially in the AccountManager.swift file - so let's start there. The original Shiny gives us some hints on where it needs to be amended.

The only external library we have added to the code is Alamofire to comfortably make HTTP requests.

In the steps above you have already modified the first line of code in the AccountManager: you have set the domain of your web app. You have set up the Apple site association prior as well. These steps are crucial, as they are the foundation to share credentials between your web app and the native app we are looking at right now. The domain name in this case will be used to create login challenges and validate them via http calls to your web app.

Signing in

The first function we need to amend is the signInWith() function. To sign a user in we first need to fetch a unique challenge from the Hanko Authentication API via our web app. This challenge will be signed with the passkey and returned to the web app for validation, again utilizing the Hanko Authentication API.

We have our first encounter with Apple's new API right at the beginning of the signInWith() function:

let publicKeyCredentialProvider = ASAuthorizationPlatformPublicKeyCredentialProvider(relyingPartyIdentifier: domain)

This creates a provider to work with a passkey stored in the iCloud Keychain. It takes our domain as the only option for now.

Getting the challenge

Next, we are fetching the challenge from the server with the getAuthenticationOptions() function and have the result available in the assertionRequestOptions variable in the following function block:

getAuthenticationOptions() { assertionRequestOptions in ... }

The getAuthenticationOptions() function itself basically calls our web app's /authentication_initialize endpoint, we have used that endpoint in the browser flow as well:

func getAuthenticationOptions(completionHandler: @escaping (CredentialAssertion) -> Void) {
    AF.request("https://\(domain)/authentication_initialize", method: .get).responseDecodable(of: CredentialAssertion.self) { ... }
}

The actual challenge is delivered to us Base64URL encoded. The object used to store the response is the CredentialAssertion object defined in the Models.swift file. Go check it out - it is pretty straight forward. As Swift does only deal with plain Base64 we are using a helper function to convert the challenge:

let challenge = assertionRequestOptions.publicKey.challenge.decodeBase64Url()!

You can find the decodeBase64Url() function at the end of the AccountManager.swift file. It takes an Base64URL string as an input. Basically it replaces a few characters and sorts out the padding. As a result it gives us plain Base64.

Once we have our challenge we can proceed to create the assertion request. This request will be signed with the passkey. We are using the publicKeyCredentialProvider which we have created earlier for that:

let assertionRequest = publicKeyCredentialProvider.createCredentialAssertionRequest(challenge: challenge)

Next we check if we require user verification and enable it:

if let userVerification = assertionRequestOptions.publicKey.userVerification {
    assertionRequest.userVerificationPreference = ASAuthorizationPublicKeyCredentialUserVerificationPreference.init(rawValue: userVerification)
}

Please admire Apple's new beautiful API at this point for a second: ASAuthorizationPublicKeyCredentialUserVerificationPreference. Feels a bit like the German Donaudampfschiffahrtskapitänsmütze...

User Verification is ...

The technical process by which an authenticator locally authorizes the invocation of the authenticatorMakeCredential and authenticatorGetAssertion operations.

So, if a relying party, a.k.a. your web app, requires User Verification, it actually triggers the local authentication in the means of Touch ID, Face ID, or PIN/password to unlock your Keychain.

Please keep in mind that your biometrics, your PIN, or your password WILL NEVER LEAVE YOUR DEVICE!

Signing the challenge with your passkey

To finally sign our login challenge (a.k.a. assertion request) we create an ASAuthorizationController and hand it over our assertionRequest.

// Pass in any mix of supported sign in request types.
let authController = ASAuthorizationController(authorizationRequests: [ assertionRequest ] )
authController.delegate = self
authController.presentationContextProvider = self
authController.performRequests()

If you compare this to the original Shiny app you can see that you could also send password credentials at this point. We have removed this part for the sake of focus, clarity and because our web app purposefully does not do passwords.

It is important to understand that our AccountManager class implements the ASAuthorizationControllerDelegate interface. The official Apple documentation defines delegation as:

Delegation is a design pattern that enables a class to hand off (or “delegate”) some of its responsibilities to an instance of another class.

So when the performRequests() method is called at the end, our own authorizationController() function is being called, because we have delegated it to ourselves with the authController.delegate = self two lines earlier. We have two versions of the authorizationController(), one for the success case and one for the failure.

func authorizationController(controller: ASAuthorizationController, didCompleteWithAuthorization authorization: ASAuthorization) {...}

func authorizationController(controller: ASAuthorizationController, didCompleteWithError error: Error) {...}

Let's have a look at the happy-path :) During the authController.performRequests() execution, right before our authorizationController() is being called, the user has been presented with the prompt to unlock the Keychain, asking for Touch ID, Face ID, or the local device's PIN. In our case the passkey connected with the domain has been granted access to and was used to sign the challenge.

We have an ASAuthorization object now and it contains the asserted credentials, stored in the credential property - it's an ASAuthorizationPlatformPublicKeyCredentialAssertion in Apple API speak :D These asserted credentials are being sent to your web app's backend using the sendAuthenticationResponse() function to verify them with the Hanko API.

func authorizationController(controller: ASAuthorizationController, didCompleteWithAuthorization authorization: ASAuthorization) {
    ...
    switch authorization.credential {
    ...
    case let credentialAssertion as ASAuthorizationPlatformPublicKeyCredentialAssertion:
        logger.log("A credential was used to authenticate: \(credentialAssertion)")
        // After the server has verified the assertion, sign the user in.
        sendAuthenticationResponse(params: credentialAssertion) {
            self.didFinishSignIn()
        }
    ...
}

On success, the didFinishSignIn() function is being called, which in turn triggers the presentation of the screen for a signed-in user – today's Shiny!

And while we are at it: the first occasion that triggers the signInWith() function is the viewDidAppear() method of the SignInViewController. So right at the start of our app it tries to sign in the user, using a passkey that is registered for your domain. If there is no matching passkey on your iPhone or iPad, nothing visible happens. In our debug environment we can see an error message in the console in that case, courtesy to our logger.log() call.

Registering a new account

To be able to register a new passkey-protected account, we create the function signUpWith() in the AccountManager class. This function essentially takes a username, tries to register an account with our web app and subsequently creates a new passkey for it.

We start off like the signInWith() function by creating a publicKeyCredentialProvider:

func signUpWith(userName: String, anchor: ASPresentationAnchor) {
    self.authenticationAnchor = anchor
    let publicKeyCredentialProvider = ASAuthorizationPlatformPublicKeyCredentialProvider(relyingPartyIdentifier: domain)

    getRegistrationOptions(username: userName) /* ... */
}

To register our desired username with the web app, we are using the getRegistrationOptions() method defined in our AccountManager class. It makes use of our web app's /registration_initialize endpoint with the username as GET parameter:

func getRegistrationOptions(username: String, ...) {
    AF.request("https://\(domain)/registration_initialize?user_name=\(username)", method: .get). /* ... */
}

Looking once again at the happy path, in case of success we receive a creationRequest object. We are picking the challenge and user ID from it, converting them from Base64URL to Base64 in the process. We use both to create our actual credentials creation request, based on the publicKeyCredentialProvider object:

func signUpWith(userName: String, anchor: ASPresentationAnchor) {
    /* ... */

    getRegistrationOptions(username: userName) { creationRequest in
        let challenge = creationRequest.publicKey.challenge.decodeBase64Url()!
        let userID = creationRequest.publicKey.user.id.decodeBase64Url()!
        let registrationRequest = publicKeyCredentialProvider.createCredentialRegistrationRequest(challenge: challenge,name: userName, userID: userID)
        /* ... */
    }
}

User verification and device trust model

In case our web app would require some sort of attestation (device or authenticator trust model, see below) or user verification we extract them from the creationRequest just like the challenge and user ID before and apply them to the registrationRequest:

getRegistrationOptions(username: userName) { creationRequest in
    /* ... */
    if let attestation = creationRequest.publicKey.attestation {
        registrationRequest.attestationPreference = ASAuthorizationPublicKeyCredentialAttestationKind.init(rawValue: attestation)
    }

    if let userVerification = creationRequest.publicKey.authenticatorSelection?.userVerification {
        registrationRequest.userVerificationPreference = ASAuthorizationPublicKeyCredentialUserVerificationPreference.init(rawValue: userVerification)
    }

    /* ... */
}

Attestation serves the purpose of providing a cryptographic proof of the authenticator attributes to the relying party in order to ensure that credentials originate from a trusted device with verifiable characteristics.

-- Hanko documentation: Authenticator trust model

Having assembled the registrationRequest we now proceed with the authController like before during sign in.

getRegistrationOptions(username: userName) { creationRequest in
    /* ... */

    let authController = ASAuthorizationController(authorizationRequests: [ registrationRequest ] )
    authController.delegate = self
    authController.presentationContextProvider = self
    authController.performRequests()
}

Having delegated the authorizationController to ourselves (see above), this time the switch catches on the ASAuthorizationPlatformPublicKeyCredentialRegistration once the user has granted permission to create the new passkey. sendRegistrationResponse has the web app verify and finalize the registration on the /authentication_finalize endpoint and calls the app's didFinishSignIn() on success.

func authorizationController(controller: ASAuthorizationController, didCompleteWithAuthorization authorization: ASAuthorization) {
    let logger = Logger()
    switch authorization.credential {
    /* ... */
    case let credentialRegistration as ASAuthorizationPlatformPublicKeyCredentialRegistration:
        logger.log("A new credential was registered: \(credentialRegistration)")

        sendRegistrationResponse(params: credentialRegistration) {
            self.didFinishSignIn()
        }
        /* ... */
    }
}

This leads us to our Shiny screen again. Voilá, that's it!

I hope you have enjoyed this article. If you have any questions: just post a comment below!

Passkeys for web authentication

Jan Gerle — Mon, 21 Jun 2021 05:44:59 +0000

This is the first part of a two-part series on passkeys, as introduced by Apple at WWDC21. In this article, we will walk you through the creation of a simple web app for registration and authentication using passkeys on Apple devices with the new "passkeys in iCloud Keychain" sync feature. In part 2 of this guide, we will cover adding a sample iOS app to your setup from the guide, demonstrating a seamless user experience with passkeys across web and mobile.

Target Audience: Developers who want to try out passkeys with their website and / or app and, for that, need to adopt WebAuthn on their server.

Say hello to Apple’s embracement of WebAuthn

Apple announced at WWDC21 that WebAuthn credentials will be available as “passkeys” in the iCloud Keychain, as well as the availability of system-wide WebAuthn APIs on iOS, iPadOS, and macOS.

Passkey sign-in sequence on an Apple iPad with iOS 15

What is WebAuthn?

Passkeys are based on WebAuthn, a capability of your operating system that enables your device to store private key material (the WebAuthn credentials) and generate signatures with them to authenticate you against a web server. Sounds complicated, I know, but for the end user this breaks down to using Touch ID or Face ID on websites and apps instead of passwords. At the same time, behind the scenes, the WebAuthn protocol allows for a very strong, unphishable, cryptographic multi-factor authentication mechanism that can replace all other current second-factor methods like OTP apps or generators, SMS passcodes, or even smartcards, while being far more secure.

Passkeys = (synced) WebAuthn credentials

While the WebAuthn API has been available on all major platforms – including iOS and macOS – for some time, Apple's new "Passkeys in iCloud Keychain" feature is attempting to solve WebAuthn's biggest remaining pain point: device loss, i.e., account recovery. The synchronization of WebAuthn credentials across all devices associated with the same Apple ID enables true passwordless accounts that do not need to fall back to less secure authentication or recovery methods like passwords if you want to sign in to a website or app on a new device. Once enrolled, users can sign in with Face ID and Touch ID on all their devices (Apple-only, for now) without worrying at all about creating or memorizing a password or becoming the victim of a password-related attack like Phishing.

System-wide WebAuthn APIs for websites and native apps

The other WWDC announcement, system-wide WebAuthn APIs on iOS and macOS, is also very welcome, because the APIs enable apps and websites from the same service (i.e., the same URL) to access the same WebAuthn credentials on a device. You register in the app, and can use the same passkey via Touch ID or Face ID seamlessly on the service's website as well (and vice-versa). Another result of the APIs is that other browsers than Safari (once they implement the new APIs) can access the credentials as well. Until now, only Safari supported system-level WebAuthn credentials on iOS, iPadOS, and macOS. Apple is only catching up here though, as this feature is already present on Windows 10 ("Windows Hello") and Android.

Adopt WebAuthn on your server

In their WWDC announcement video, Apple demonstrates the creation and seamless synchronization of passkeys across devices. They even show that WebAuthn works with iOS Apps using the same passkey. How to create the server part is left opaque, though. Actually, it is just an item in their list of "Next steps" without further explanation.

‍

"Adopt WebAuthn on your server, will ya?"

In this guide, you will:

Learn how to set up a simple web server that supports WebAuthn and therefore, passkeys
Create a sample website with WebAuthn registration and authentication
Build and run a demo setup showing cross-device, end-to-end passwordless authentication on iOS 15 / macOS Monterey devices
Bonus: As it is based on pure WebAuthn, the demo will also work on Windows 10 and Android 7+ devices (only without the passkey in iCloud Keychain sync feature)

What do you need to implement passkey login and iCloud Keychain sync?

Two Apple devices to actually sync the passkeys, e.g., an iPhone with iOS 15 and a Mac with Monterey. Use Safari on both of them.
A WebAuthn-capable web app (we’ll get to that 😀)
A WebAuthn / FIDO2 server component (we happily provide the Hanko Authentication API for that 🚀)

Again – in case you are looking for the iOS app case, i.e., sharing passkeys between apps and websites, this will be the content of the second part of this guide.

Celebrating the ceremonies

Some context first: WebAuthn relies on two ‘ceremonies’, the credential registration and the actual authentication. In the WebAuthn spec, they are called ‘attestation’ and ‘assertion’, but we will stick to registration and authentication.

During registration, a unique public/private keypair is being generated. The private key – a.k.a. the passkey – is stored in the Keychain and the corresponding public key is being stored on the server. In our case at hand, the registration takes place only once, during initial user account registration. In a real world scenario, you would enable your users to add multiple WebAuthn credentials to their account on their profile page, e.g., USB/NFC Security Keys or other WebAuthn-capable devices.

Passkey creation during account registration

Following the registration, whenever a user wants to log in to the service’s website or app, instead of providing a username and password, the user requests authentication with the passkey, using the WebAuthn protocol. In our demo case, the button will just say “Login”, no other form fields are required. The user does not even need to provide a username – ain’t that cool?! No more lost usernames!

Signing in using a passkey

Access to the passkey is protected on your device with your preferred mechanism: Face ID, Touch ID, or a PIN. The passkey itself never leaves your device during registration or authentication, it is only being used locally for creating a digital signature that will be validated with the public key on the server.

Let’s get to work!

Enable Platform Authenticator Syncing

First of all, enable Platform Authenticator Syncing on your Apple devices. In iOS 15, turn on the Syncing Platform Authenticator switch under Settings > Developer. The Developer menu is available on your device when you set it up as a development device in Xcode.

Creating the WebAuthn-enabled web application

We will be using a simple html/JavaScript website with a Go backend for this demonstration. Of course you can use whatever language you are comfortable with on the server side. We choose Go, as you only need a few libraries to get the job done and it is easy to read even if you are not a Go expert.

A quick word on good security practices: This is a demo application. To keep things clean, we will not provide a lot of error handling or input sanitizing. You should not use this code in production environments.

To process WebAuthn requests in a web app, you need a WebAuthn server component, sometimes also called a "FIDO2 Server". This server is dealing with the key management on the application’s behalf, almost like a PKI. There are some open source implementations for that available on GitHub. Surely the fastest way to get WebAuthn up and running is using our Cloud-hosted Hanko Authentication API. For that you can create a free account at Hanko Dev Console and set it up according to our Getting Started Guide.

Setting up the project

We assume that you have Go installed. If not, now is the right time to do so. Another tool you need is Git – we just assume that it is installed.

Next you need to clone our repository, which contains a small ready-made web app that uses WebAuthn credentials for authentication:

git clone https://github.com/teamhanko/apple-wwdc21-webauthn-example
cd apple-wwdc21-webauthn-example

So what’s in there?

We are keeping most of the backend code in the main.go file for the sake of simplicity, with two supporting models in a subfolder.
In the config subfolder, you will find a config file named config.template.yaml. Rename it to config.yaml and complete it with your Hanko API credentials.
The three html templates needed for the frontend reside in the templates folder.
In the assets subfolder there is a file named app.js. This is our registration and authentication procedure, which will be triggered by the "Sign in" and "Register" buttons. We will take a look at these functions later.

Let’s start with the main.go:

// main.go
package main

import (
    "net/http"
    "strings"

    "github.com/gin-contrib/sessions"
    "github.com/gin-contrib/sessions/cookie"
    "github.com/gin-gonic/gin"
    "github.com/gofrs/uuid"
    log "github.com/sirupsen/logrus"
    "github.com/teamhanko/apple-wwdc21-webauthn-example/config"
    "github.com/teamhanko/apple-wwdc21-webauthn-example/models"
    "github.com/teamhanko/hanko-go/webauthn"
)
...

Pretty straight forward: we import the Go http and strings libraries, along with the Gin session middleware, the cookie library and the Gin request router. They enable us to create http endpoints to communicate with and to create cookie-based sessions for signed-in users.

To create unique ids for our users, we choose UUID and import a library for that.

Last but not least, we need the Hanko Go SDK, the corresponding configuration, and the two supporting models.

The Go app itself has a few http endpoints:

...
  r.Static("/assets", "./assets")   // static assets like images
  r.StaticFile("/favicon.ico", "./assets/favicon.ico") // a favicon :)
  r.StaticFile("/", "./index.html") // the main screen w/ login button
  r.StaticFile("/register", "./register.html")  // the registration form

  r.GET("/registration_initialize", ...)   // step 1 for registration
  r.POST("/registration_finalize", ...)     // step 2 for registration

  r.GET("/authentication_initialize", ...) // step 1 for authentication
  r.POST("/authentication_finalize", ...)   // step 2 for authentication

  r.GET("/content", ...)   // the protected content, served after login
  r.GET("/logout", ...)    // the logout url
...

Besides some static content, we can see the four endpoints needed for the two WebAuthn ceremonies: registration and authentication.

You might have noticed the initialize/finalize pattern here: Whenever we are in the WebAuthn context, we first have to do an initialization with the FIDO Server. Then we need to communicate with the Authenticator (i.e., your Mac or iPhone) using Hanko’s JavaScript SDK and pass the result to the finalize endpoint.

User signup – the registration ceremony

The first two endpoints handle the registration ceremony. When the user enters the desired username and hits the “Register” button, the JavaScript function do_reg() in our app.js calls the /registration_initialize endpoint of the web app:

// This function will be called by the “Register” button
async function do_reg(event) {
  event.preventDefault();
  const username = document.getElementById('username').value;
  let query = '?user_name=' + username;
  const regInitResponse = await fetch('/registration_initialize' + query);

...

  const creationOptions = await regInitResponse.json();
...

The endpoint will check the desired username, create a UUID, and return a JSON object which is contained in our JavaScript constant creationOptions. Let’s take a look at the backend code that creates said JSON:

... 
  // Create the request options for the Hanko API
  user := webauthn.NewRegistrationInitializationUser(userModel.ID, userModel.Name)

  authenticatorSelection := webauthn.NewAuthenticatorSelection().
    WithUserVerification(webauthn.VerificationRequired).
    WithAuthenticatorAttachment(webauthn.Platform).
    WithRequireResidentKey(true)

  request := webauthn.NewRegistrationInitializationRequest(user).
    WithAuthenticatorSelection(authenticatorSelection).
    WithConveyancePreference(webauthn.PreferNoAttestation)

  // Get the registration request from the Hanko API with the given 
  // request options
  response, apiErr := apiClient.InitializeRegistration(request)
...

First off, the code above picks up the ID and username. We need them for the call to the Hanko API. Then we set a few parameters for the WebAuthn credentials:

User Verification: Required – This triggers the Authenticator to ask for Face ID, Touch ID or a PIN whenever the new Passkey is to be used. Your device decides which mechanism is active. We want multi-factor authentication!
Authenticator Attachment: Platform – We want your Mac or your iPhone as authenticator device. Another option would be to require an USB Security Key for example.
Resident Key: True – This feature is also referred to as “Discoverable Credential” and it enables us to authenticate without a username, just by providing the passkey. Pretty convenient. We want that, so we switch it on!
Conveyance Preference: Prefer no Attestation: This determines if we want to receive so called attestation information. Think of it as a certificate about the capabilities of the Authenticator. You would be using that in a scenario with advanced security needs, e.g., in an online banking scenario. This is not the case here, so we switch it off.

The Hanko API creates a correctly formatted representation of these parameters for us, which our JavaScript picks up as mentioned above. Our app can now pass them to the browser’s WebAuthn API using Hanko’s JavaScript SDK:

‍...
      const authenticatorResponse = await hankoWebAuthn.create(creationOptions)
...

The hankoWebauthn.create() function will trigger a native dialogue in Safari to grant permission to create a new passkey by unlocking your Keychain. Once completed, we POST the authenticator’s response to the backend:

...
      const registrationResponse = await fetch('/registration_finalize', {
          method: 'POST',
          body: JSON.stringify(authenticatorResponse)
      })
...

The backend at /registration_finalize receives this response and calls the Hanko API again, completing the registration ceremony.

...
 // Send the authenticator response to the Hanko API
 r.POST("/registration_finalize", func(c *gin.Context) {
    // Parse the authenticator response
    request, err := 
    webauthn.ParseRegistrationFinalizationRequest(c.Request.Body)
...
    response, apiErr := apiClient.FinalizeRegistration(request)
    // on success create the user session
...

Once this is successful, the browser will be redirected to the /content endpoint of the web app:

...
      if (!registrationResponse.ok) {
          const error = (await registrationResponse.json()).error
          showRegError(error)
      } else {
          location.assign('/content') // redirect on success
      }
...

Well done! You are now registered with your passkey 🥳

As you have just registered your passkey, the application now considers you as “signed in”. Because of Apple’s new syncing feature, the passkey is now already available on your companion device – let’s assume that this is your iPhone.

To move on to the next step, press the “Logout” button in the upper right corner. This takes you to the /logout endpoint, terminating your session, and immediately redirecting you to the start page. Now we can proceed to the second ceremony.

User login – the authentication ceremony

The only thing we need to create the ultimate login experience is: A "Sign in" button 😉 and a rather simple JavaScript function do_auth() to trigger the login process. No need for a separate username field, as we are using the domain name and the UUID as our common identifier behind the scenes. Passkeys are fixed to a specific domain.

Let’s have a look at the first half of the do_auth() function:

async function do_auth(event) {
    ...
    const authInitResponse = await fetch('/authentication_initialize')

    const authOptions = await authInitResponse.json()
    const authenticatorResponse = await hankoWebAuthn.get(authOptions)
...

This function first calls the backend’s /authentication_initialize endpoint, which creates request options like we did during registration. The resulting request options object is passed to Safari’s WebAuthn API using Hanko’s Javascript SDK function hankoWebAuthn.get(authOptions).

The corresponding backend code using the Hanko SDK is rather short:

// Get an authentication request from the Hanko API
r.POST("/authentication_initialize", func(c *gin.Context) {
    // Create the request options
    request := webauthn.NewAuthenticationInitializationRequest().
        WithUserVerification(webauthn.VerificationRequired).
        WithAuthenticatorAttachment(webauthn.Platform)

    // Get the authentication result from the Hanko API with the 
    // given request options
    response, apiErr := apiClient.InitializeAuthentication(request)
    if apiErr != nil {
        c.JSON(apiErr.StatusCode, gin.H{"error": apiErr.Error()})
        return
    }

    c.JSON(http.StatusOK, response)
})

Just like at registration, a native OS dialogue will show up. You are being presented with a list of registered passkeys and can confirm usage with a simple click.

Again, the passkey is being used to sign the request, the key itself will not leave your device! Once a passkey has successfully been used, the resulting Authenticator response is sent to the Hanko API for validation, using the backend’s /authentication_finalize endpoint.

Now to the second half of the do_auth() function in our frontend:

...
    const authenticationResponse = await fetch('/authentication_finalize', {
        method: 'POST',
        body: JSON.stringify(authenticatorResponse)
    })

    if (!authenticationResponse.ok) {
        console.log((await authenticationResponse.json()).error)
    } else {
        location.assign('/content') // login successful
    }
}

The backend code takes the response from the authenticator and validates it against the Hanko API. In case of success, a session is being created and the frontend code redirects to our private /content page.

// Send the authenticator response to the Hanko API
r.POST("/authentication_finalize", func(c *gin.Context) {
    // Parse the authenticator response
    request, err := webauthn.ParseAuthenticationFinalizationRequest(c.Request.Body)
...

    // Send the authenticator reponse to the Hanko API for validation
    response, apiErr := apiClient.FinalizeAuthentication(request)
    if apiErr != nil {
        c.JSON(apiErr.StatusCode, gin.H{"error": apiErr.Error()})
        return
    }

    // If no error occurred during the authenticator response validation,
    // create a session for the given user
    session := sessions.Default(c)
    session.Set("userId", response.Credential.User.ID)
    session.Save()

    c.JSON(http.StatusOK, response)
})

That’s it!

You are signed in, using only a passkey that is protected and unlocked by your preferred local authentication mechanism: Face ID, Touch ID or a PIN. Try the login with your iPhone, it just works without registering again – no passwords involved!

The generated passkey is automatically available on your other devices with the same Apple ID

See the demo in action

Of course we have prepared a running example for you, just in case. You can find it here.

And you can access the complete source code of this project on our GitHub.

Now, as WebAuthn is a widely adopted internet standard, this demo also works using other browsers and platforms. Give it a try, invite your friends, your mom, and your co-workers to join the fun and feel the difference of a convenient and highly secure login experience. WebAuthn powered by the Hanko API 💪

See you for part 2 of this guide where we will add Apple's Shiny iOS app to our little demo setup. Stay tuned...

‍

If you enjoyed this guide, have a question, or any thoughts how we can improve, please comment or reach out.