How embesozzi/keycloak-webauthn-conditional-mediation works
Project Type and Purpose
• This project is an extension (or Service Provider Interface, SPI) for Keycloak. Its purpose is to provide a custom WebAuthn Conditional Mediation Authenticator that enhances the default authentication experience by incorporating passkey autofill (conditional UI) for supported browsers, while also falling back to username and password login where needed.
• The README and file tree make it clear that this is not a full standalone application but rather a plugin designed to be deployed within an existing Keycloak (Quarkus-based) environment.
File Structure
• Top-level files like pom.xml indicate that it is a Maven-based Java project.
• The src/main/java directory shows the Java source code. Under the package "com.twogenidentity.keycloak.authenticator", you have the main authenticator class (WebAuthnConditionalMediationAuthenticator) and its associated Factory class (WebAuthnConditionalMediationAuthenticatorFactory) that follow Keycloak’s SPI pattern.
• The src/main/resources folder includes:
• META-INF/services entries for registering the authenticator with Keycloak. This allows the Keycloak platform to discover and load the custom authenticator.
• theme-resources that contain the Freemarker template (webauthn-conditional-mediation-authenticate.ftl) used to adjust the UI for the authentication flow.
• The .github directory, pom.xml, and README indicate CI/CD configuration and build instructions. This is useful for deployment pipelines but not central to the runtime architecture.
a. Main Components:
• Keycloak Server: Represent the core Keycloak authentication system, which orchestrates browser-based login flows.
• Custom Authenticator Extension: A component depicting the WebAuthnConditionalMediationAuthenticator along with its Factory.
• UI Template: The Freemarker-based template (webauthn-conditional-mediation-authenticate.ftl) that customizes the authentication page.
• META-INF Services Registration: A block indicating the service registration mechanism used to inform Keycloak about this custom authenticator.
• Deployment Environment: Indicate the usage in a Quarkus-based distribution (or Docker container), where the built JAR is deployed to the Keycloak providers folder.
b. Relationships and Interactions:
• The Keycloak Server invokes the custom authenticator during the browser login flow.
• The authenticator (and its factory) are discovered via the META-INF/services mechanism.
• The authenticator uses the UI template to render the conditional UI for WebAuthn login (passkey autofill), and falls back to other authentication methods if necessary.
c. Highlighted Architectural Patterns:
• SPI (Service Provider Interface) Extension: The use of the META-INF/services mechanism shows the adherence to SPI, allowing for plug-and-play extensibility.
• Separation of Concerns: The authentication logic is decoupled from the UI rendering (handled via Freemarker templates), ensuring that each component has a clear responsibility.
• Conditional Behavior: The logic to check for browser support (enabling passkey autofill versus showing a default button) is encapsulated within the custom authenticator.
d. Relevant Technologies, Frameworks, or Libraries:
• Java & Maven: Core development and build technologies.
• Keycloak & its SPI Framework: The integration framework that allows custom providers.
• Freemarker: Template engine used for UI customization.
• Quarkus (and Docker if applicable): Deployment environment guidelines.