Keycloak QR Code Authentication

Sign in to Keycloak with another device using QR codes.

This extension for Keycloak provides an execution enabling users to complete authentication with another device.

With QR code authentication, users can authenticate without typing passwords or sharing passwords on untrusted devices. It also allows usage of Passkeys on devices without Bluetooth by completing authentication with a passkey on enabled device.

Features

There are two executions available: QR Code Sign In and Username Password Form with Optional QR Code Login

Both executions provide:

• Authentication executions available in browser bound flows
• Confirmation of session id (tabID) on confirmation page
• Confirmation of User Agent and originating device information on the confirmation page
• ACR Transfer between sessions, complete required ACR flows on another device

The QR Code Sign In execution:

• Sign in page refreshes automatically to check if another device has completed authentication
• Does not require new ftl templates when custom themes are used

The Username Password Form with Optional QR Code Login execution:

• Builds on keycloak.v2 login.ftl template
• Requires a custom qr-login.ftl template if the realm uses a custom theme (see Template Themes)
• Sign in page provides default username password field and optional QR code.

Compatibility

	v0.2.x	v0.3.x
KC 26.3.x	☑️
KC 26.4.x	✅
KC 26.5.x	➖	✅

✅ - Compatible
➖ - Patch only
☑️ - Not validated

Installation

1. Download the latest compatible release from the releases page
2. Save the downloaded JAR file into the providers/ directory inside Keycloak installation folder
3. Stop the Keycloak server
4. Rebuild the installation using kc.sh build command
5. Start Keycloak

Configuration

No configuration needed if Username Password Form with Optional QR Code Login is not used. QR Code Sign In can just be added to your browser flow.

Refresh Rate and Login Timeout:

• Refresh rate sets how often the login page reloads to check if a user has authenticated
• Login timeout sets how long the user has before the flow is invalidated
• Note: If the Refresh Rate is zero or less than Login Timeout, the QR code will display even when the flow has expired/invalidated.

ACR Transfer:

• When enabled, the required ACR on the originating session will be the required ACR on the device completing authentication.
• Once authenticated, the authenticated LoA level will be set on the originating session.
• The ACR LoA mapping of the originating client will be used when available, otherwise the realm default is used.

❗ The device authenticating uses the realm default browser flow, not the client specific flow from the originating session. This can be modified by changing the flow in the QR Code Login Extension client.

Credential Type Transfer:

• When enabled, the credential types used on the device completing authentication will be transferred to the originating session.
• Useful when the flow has conditions on credential type.
• Requires the usage of Remember Credential Type executor in the flow used by ClientID com-hadleyso-keycloak-qrauth-rest-client (typically realm default browser).

Template Themes

The ftl templates can be overridden. This is optional, unless the Username Password Form with Optional QR Code Login execution is used in a realm with a custom theme.

qr-login.ftl - for Username Password Form with Optional QR Code Login

• Based on login.ftl from keycloak.v2 theme
• Requires macro import <#import "qrLogin.ftl" as qrlogin>
• To render QR code <@qrlogin.qrLogin />

qr-login-scan.ftl - for QR Code Sign In when QR code is displayed

• requires QRauthImage to provide the QR Code PNG in base64

qr-login-verify.ftl- for QR Code Sign In after the user authenticates, prompts to reject or approve

• requires ${approveURL} to approve the sign in and ${rejectURL} to reject.
• optional originating device info: ${ua_device}, ${ua_os}, ${ua_agent}, and ${local_localized}

Messages

Only English and German is provided, see messages_en.properties and messages_de.properties.

QR Code Information

The QR code and the token encoded in the QR code exposes the following to all users, even when unauthenticated:

• Keycloak public FQDN
• Realm Name
• Keycloak session ID
• Keycloak tab ID

It exposes the following to authenticated users:

• Originating device user agent OS
• Originating device user agent device
• Originating device user agent agent name
• Originating device locale (Accept-Language header)
• Originating device locale language name, country name, and variant, localized

License

Keycloak QR Code Authentication (keycloak-extension-qr-code-execution / com.hadleyso.keycloak.qrauth) is distributed under GNU Affero General Public License v3.0. Copyright (c) 2025 Hadley So.