Introduction to Keycloak Passkeys Integration

Integrating passkey authentication into applications with an existing Keycloak user base can seem daunting. Keycloak’s native passkey implementation can be complex and user-unfriendly. To streamline this process, Corbado’s passkey-first web component offers a more user-friendly experience, automatically connecting to a hosted passkeys backend. This approach ensures existing accounts can continue using passwords as a fallback, while new users signing up with a passkey are still managed through Keycloak.

Prerequisites and Setup

Before diving into the implementation, it’s important to have a basic understanding of HTML, JavaScript (particularly Node.js/Express), Docker, and Keycloak​​. The setup involves a dockerized environment with two containers: one for the Express application and another hosting Keycloak with its functionalities and databases​​.

Building the Application Structure

The application structure is crucial for seamless integration. It includes controllers like authController.js for rendering views and handling sessions, and corbadoWebhookController.js for managing Corbado webhook requests. The routes are defined in authRoutes.js and corbadoWebhookRoutes.js, with a dedicated userService.js for communication with Keycloak. The views are managed through templates like login.ejs and profile.ejs​​.

Find the full GitHub repository here.

Account and Application Configuration

Setting up a Corbado account is the first step, where you choose ‘Web app’ as the app type and indicate that the app already has users. Detailed information about the tech stack and goals helps tailor the Corbado experience​​. Configuration also involves setting up URLs for application, redirect, and relying party ID​​.

Keycloak Configuration

Setting up Keycloak involves using its Docker image, initializing it with admin credentials, and accessing the admin console to manage users and credentials​​.

Developing the Express Application

The Express app forms the backbone of the integration. It includes importing necessary modules, configuring the environment, and setting up routes and views. The application listens on a specified port, ready to handle requests​​.

Environment and User Service Setup

Environmental variables like Corbado project ID, API secret, and Keycloak details are crucial for the setup. These are stored in a .env file for secure and convenient access​​. The user service utilizes Keycloak's Admin API, allowing for essential functionalities like fetching user data and verifying credentials​​.

Creating the Login Page and Profile Page

The login page is created using HTML templates and includes the Corbado web component for authentication. This setup provides a seamless user experience while maintaining the application’s aesthetic consistency​​. After successful authentication, the user is redirected to the profile page, which displays user information and includes a logout option​​.

Implementing Corbado Node.js SDK and Webhooks

The Corbado Node.js SDK is essential for retrieving the current user’s details and managing authentication flows. It’s used alongside the user service for effective user management​​. Additionally, password-based authentication is enabled as a fallback through webhooks, ensuring existing users are not locked out during the transition​​.

Local Testing and CLI Integration

Using the Corbado CLI, a tunnel is created from the local environment to the Corbado server, allowing for local webhook testing and integration. This step is crucial for ensuring that the integration works as expected before going live​​.

Deployment and Testing

The final step involves deploying the application using Docker and testing it locally. The Corbado web component becomes visible, and users have the option to create a passkey for future logins​​.

Conclusion and Further Reading

This tutorial highlights the ease of adding passwordless authentication with passkeys to Keycloak-based apps using Corbado. It showcases how existing password-based users can be comfortably integrated using webhooks. For more in-depth information and to stay updated on passkeys, visit the Corbado documentation, join the Passkeys Community​​ or subscribe to the Passkeys Substack.

To explore more about this implementation and for detailed insights, visit Corbado’s Blog on Keycloak Passkeys.