Keycloak WebAuthn Passkey Without Keycloaks Frontend using Rest Api

Question

I am trying to setup Keycloak with WebAuthn Passkey but every documentation leads to users to having to be redirected to Keycloak's frontend. Is there a way to have your own frontend and send the data to Keycloak's API? Have yet to find a solution for this.

I already have the normal username + password flow running using the API and my own frontend form but cannot find any interfaces of Keycloak's API Documentation. I have no problem with building alot myself but Keycloak needs to have some way of accepting that client data to either register or auth the user's device(s) using their API.

I am using keycloak version 22

Answer 1

I've had a similar scenario to this, and also had trouble looking through the Keycloak documentation to understand the best approach. Through experimentation, I've found three different approaches to this, with one that I'd ultimately recommend; but I'd also love if anyone in the Keycloak community has other recommendations.

This answer will link out to implementation guidance, but what is written below should ultimately help you from an architectural decisions standpoint.

Pass WebAuthn data through a direct access grant flow

This was the first approach that we took. We essentially use a modified direct access grant flow; instead of passing a username + password, we passed the WebAuthn assertion response to be processed by a custom Authentication SPI. This allowed us to continue to use the custom login form on our React front end.

This still involved a redirect to Keycloak, but it didn't require any user input.

While this method "worked", we ultimately decided to try a more correct approach by moving the login form (with the WebAuthn calls) directly into Keycloak.

Some issues with this approach:

• The client and keycloak are now tightly coupled, and changes will need to be made on both your client and the new SPI
• Tight coupling will also make it harder to move to a new IDP to support SSO or federation
• User credentials are exposed outside of your IDP. This isn't as big of an issue with FIDO2, but if your backend isn't checking for replay attacks then it can lead to unwanted access

There's definitely more reasons, but you probably get the point.

Implementation examples: Client [1] [2], Keycloak [1]

WebAuthn in Keycloak custom template (Recommended approach)

Keycloak has it's own WebAuthn implementation, but we needed our own custom example to handle both a different look and feel for the form itself, and some custom backend features using a different WebAuthn library.

This example used a standard OAuth redirect from our React client to Keycloak itself; all auth and user registrations happen from within Keycloak, using a custom Authentication SPI.

Building our auth forms was more complicated this way, but felt more correct, secure, and conformant with standard OAuth practices. For a production deployment, both your client, and keycloak can be proxied behind the same domain, so your users won't ever feel like they're leaving your app

Implementation examples: Client redirect [1] [2], Keycloak [1] [2]

*Note in the 2nd Keycloak example that we're calling to another API to get the PublicKeyCredentialRequestOptions, but you can self-generate these in the SPI itself.

Custom Keycloak REST API

You can extend the Keycloak API to create your own WebAuthn endpoints. Essentially you can create these endpoints, and have your client call to them to perform specific actions. While this method may look enticing, note that aside from implementing the new API methods, you'll also need to think of how to secure these endpoints as they are used by non-authenticated users (and in some cases, users who need to register). I haven't explored this option much as it's never been entirely straight forward, and I would recommend avoiding this approach for the same reasons listed for the direct access grant flow.

Hope this helps