How to Implement Passkeys in Astro Apps

Looking for a dev-focused passkey reference? Download our Passkeys Cheat Sheet. Trusted by dev teams at Ally, Stanford CS & more.

Get Cheat Sheet

In this blog post, we'll guide you through building an Astro application with passkey login functionality using the Corbado web-js component. Astro is an all-in-one web framework designed to simplify website creation. It boasts the performance and Corbado simplifies the integration of secure passkey authentication into your web apps. We'll show you how to embed Corbado's UI components and set up a secure login system. If you want to see the complete code, check out our sample Astro passkey application repository on GitHub. Here's a preview of the final passkey login interface with Astro:

This tutorial assumes you have a basic understanding of Astro, HTML, CSS, and JavaScript. To get started, make sure you have Node.js and Npm installed on your machine. For this example, we'll be using the latest version of Astro (version 4.12.3). Let's start building our secure passkey login application!

Subscribe to our Passkeys Substack for the latest news.

Subscribe

Let's explore the structure of our repository (full Astro passkeys GitHub repository). This organized architecture will help us efficiently manage and scale our Astro application.

.
├── src
│   ├── components
│   │   └── PasskeyList.astro
│   ├── layouts
│   │   └── Layout.astro
│   ├── pages
│   │   ├── index.astro
│   │   └── profile.astro
├── .env
├── package.json

Here's a brief explanation of the relevant files and directories:

• src/components/PasskeyList.astro: Component for displaying the list of passkeys.
• src/pages/index.astro: Component for the sign-up/login screen.
• src/pages/profile.astro: Component for the user profile information shown after successful authentication.
• .env: Environment variables for configuring the application.
  

  Become part of our Passkeys Community for updates & support.

  Join

In this section, we'll explain step-by-step how to set up the Astro project. Let's get started by initializing a new Astro project:

npm create astro@latest astro-passkeys-app
cd astro-passkeys-app
npm install

Next, install the necessary dependencies:

npm install @corbado/web-js

To start the development server and see the basic skeleton of your application, run:

npm run dev

Your application will start at http://localhost:4321. You should now see the basic structure of your Astro application.

To integrate Corbado's UI components in your Astro application, you need to follow these steps.

Visit the Corbado developer panel to sign up and create your account. You'll experience the passkey sign-up in action here!

In the project setup wizard, begin by selecting an appropriate name for your project. For the product selection, opt for "Corbado Complete". Subsequently, select "DEV environment" along with "Corbado session management" options. Afterwards, you'll get more foundational setup guidance. Next, choose "Web app" as an application type and VanillaJS as your frontend framework (as Astro supports JavaScript, we can use the VanillaJS UI components). In the application settings, define your Application URL and Relying Party ID as follows:

• Application URL: Provide the URL where you embedded the UI component, here: http://localhost:4321
• Relying Party ID: Provide the domain (no protocol, no port, and no path) where passkeys should be bound to, here: localhost Lastly, navigate to the Corbado project settings to find your project ID under Corbado API access. Then, store the project ID in your environment file. Your environment file should look like this:

PUBLIC_CORBADO_PROJECT_ID=<YOUR_PROJECT_ID>

You'll need this project ID later to embed the Corbado UI component in your Astro app.

To get started with embedding the Corbado UI component in your Astro frontend, follow these steps:

• Initialize the Corbado Project: The corbadoSetup.js file contains the shared logic for initializing Corbado. This file ensures that you only need to write the initialization logic once and reuse it across different components. Here’s the complete code of the corbadoSetup.js file:

const projectId = import.meta.env.PUBLIC_CORBADO_PROJECT_ID;
export const loadCorbadoProject = async () => {
    await Corbado.load({
        projectId: projectId,
    });
};

• Set Up the Login Component: The index.astro component will handle user authentication by embedding Corbado's UI component. Here’s the complete code of the index.astro component:

---
---
<html>
  <head>
    <title>Login</title>
    <link
      rel="stylesheet"
      href="https://unpkg.com/@corbado/web-js@latest/dist/bundle/index.css"
    />
    <style>
      body,
      html {
        height: 100%;
        margin: 0;
        display: flex;
        justify-content: center;
        align-items: center;
        font-family: Arial, sans-serif;
      }
      .container {
        text-align: center;
      }
      button {
        margin-top: 10px;
        padding: 10px 20px;
        font-size: 16px;
      }
    </style>
    <script src="https://unpkg.com/@corbado/web-js@latest/dist/bundle/index.js"
    ></script>
  </head>
  <body>
    <div class="container">
      <div id="corbado-auth"></div>
    </div>
    <script type="module">
      import { loadCorbadoProject } from "./corbadoSetup.js";
      const initializeCorbado = async () => {
        await loadCorbadoProject();
        const authElement = document.getElementById("corbado-auth");
        Corbado.mountAuthUI(authElement, {
          onLoggedIn: () => {
            window.location.href = "/profile";
          },
        });
      };
      initializeCorbado();
    </script>
  </body>
</html>

The PasskeyList.astro component will display a list of passkeys. This component will be integrated into the Profile component. Here’s the complete code of the PasskeyList.astro component:

<div id="passkey-list"></div>
<script type="module">
  import { loadCorbadoProject } from "./corbadoSetup.js";
  const initializePasskeyList = async () => {
    await loadCorbadoProject();
    const passkeyListElement = document.getElementById("passkey-list");
    if (Corbado.user) {
      Corbado.mountPasskeyListUI(passkeyListElement);
    }
  };
  initializePasskeyList();
</script>

The profile.astro component will fetch and display user information using Corbado's API. It will also provide a UI for managing passkeys and logging out. Here’s the complete code of the profile.astro component:

---
import PasskeyList from "../components/PasskeyList.astro";
---
<html>
  <head>
    <title>Profile</title>
    <link
      rel="stylesheet"
      href="https://unpkg.com/@corbado/web-js@latest/dist/bundle/index.css"
    />
    <style>
      body,
      html {
        height: 100%;
        margin: 0;
        display: flex;
        justify-content: center;
        align-items: center;
        font-family: Arial, sans-serif;
      }
      .container {
        text-align: center;
      }
      button {
        margin-top: 10px;
        padding: 10px 20px;
        font-size: 16px;
      }
    </style>
    <script src="https://unpkg.com/@corbado/web-js@latest/dist/bundle/index.js"
    ></script>
  </head>
  <body>
    <div class="container">
      <h1>Profile</h1>
      <div id="profile-content"></div>
      <PasskeyList />
      <button id="logout-button" style="display: none;">Logout</button>
    </div>
    <script type="module">
      import { loadCorbadoProject } from "./corbadoSetup.js";
      const initializeProfile = async () => {
        await loadCorbadoProject();
        const user = Corbado.user;
        const profileContent = document.getElementById("profile-content");
        const logoutButton = document.getElementById("logout-button");
        if (user) {
          profileContent.innerHTML = `<p>Welcome, ${user.email}</p>`;
          logoutButton.style.display = "block";
          logoutButton.addEventListener("click", () => {
            Corbado.logout();
            window.location.href = "/login";
          });
        } else {
          profileContent.innerHTML =
            '<p>Please <a href="/login">login</a> to view your profile.</p>';
        }
      };
      initializeProfile();
    </script>
  </body>
</html>

Now, when you start your development server with

npm run dev

and navigate to http://localhost:4321, you should see the authentication UI.

Once logged in, you'll be redirected to the profile page displaying user details and passkey list feature.

In this tutorial, we've covered how to set up an Astro application with Corbado’s web-js component for passkey authentication. This includes initializing an Astro project, integrating Corbado for authentication, and creating a profile page with logout functionality. With these steps, you should have a functional passkey login system in your Astro application. Besides the passkey-first authentication, Corbado provides simple session management, that we used for a retrieval of basic user data. If you want to read more about how Corbado's session management please check the docs here.

Create a shared corbadoSetup.js file that exports a loadCorbadoProject() async function calling Corbado.load() with your project ID. Import and call this function in each component (index.astro, PasskeyList.astro and profile.astro) to reuse the initialization logic without duplicating it.

Astro supports JavaScript natively but does not require a specific frontend framework, so the VanillaJS @corbado/web-js package is the correct choice. You select VanillaJS as the frontend framework in the Corbado developer panel when configuring a Web app project.

Set the Application URL to http://localhost:4321 (the default Astro dev server address) and the Relying Party ID to localhost only, with no protocol, port or path included. The Relying Party ID is the domain to which passkeys are cryptographically bound.

After a successful passkey login, Corbado exposes a Corbado.user object containing basic user data such as email. Corbado Complete includes built-in session management, so no separate session library is needed to retrieve and display that user information on the profile page.