Adding and improving WebAuthn error messages by uzmamansoor09 · Pull Request #50654 · keycloak/keycloak

uzmamansoor09 · 2026-07-07T14:06:46Z

Improving how WebAuthn error messages are handled and displayed to the end-user.
Introducing error mapping for the most common WebAuthn error scenarios (such as user cancellation, an authenticator already being registered, operation timeouts, or blocked AAGUIDs) to individual message keys. For generic or unexpected errors, a generic message is shown instead, while the specific technical details from webauthn4j are written to the server logs.

Copilot

Pull request overview

This PR improves how WebAuthn/Passkey errors are presented to end users by mapping common browser/API and policy-related failures to dedicated, localizable message keys, while avoiding exposing raw technical exception text in the UI.

Changes:

Replaces WebAuthn UI error strings that previously surfaced raw {0} technical details with localized, user-friendly messages.
Introduces message-key mapping for common browser WebAuthn API error scenarios and for specific registration policy violations (AAGUID/attestation/attachment).
Updates integration tests to assert the new end-user-facing messages.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
themes/src/main/resources/theme/base/login/messages/messages_en.properties	Updates existing WebAuthn error messages and adds new localized keys for common scenarios.
services/src/main/java/org/keycloak/services/messages/Messages.java	Adds new message-key constants for specific WebAuthn error cases.
services/src/main/java/org/keycloak/authentication/requiredactions/WebAuthnRegister.java	Maps browser errors to specific message keys; introduces policy exception type carrying a localizable message key; removes technical details from UI error rendering.
services/src/main/java/org/keycloak/authentication/authenticators/browser/WebAuthnAuthenticator.java	Maps browser `.get()` errors to specific message keys and ensures UI no longer displays raw technical details.
testsuite/integration-arquillian/tests/base/src/test/java/org/keycloak/testsuite/webauthn/registration/WebAuthnOtherSettingsTest.java	Updates existing assertions and adds coverage for new browser API error-to-message mapping.
testsuite/integration-arquillian/tests/base/src/test/java/org/keycloak/testsuite/webauthn/registration/AuthAttachmentRegisterTest.java	Updates assertions to validate the new attachment mismatch end-user message.

keycloak-github-bot

Unreported flaky test detected, please review

keycloak-github-bot · 2026-07-08T10:43:13Z

Unreported flaky test detected

If the flaky tests below are affected by the changes, please review and update the changes accordingly. Otherwise, a maintainer should report the flaky tests prior to merging the PR.

org.keycloak.testsuite.forms.BruteForceTest#testExceedMaxTemporaryLockouts

Keycloak CI - Base IT (5)

org.opentest4j.AssertionFailedError: Expected error event ==> expected: <true> but was: <false>
	at org.junit.jupiter.api.AssertionFailureBuilder.build(AssertionFailureBuilder.java:151)
	at org.junit.jupiter.api.AssertionFailureBuilder.buildAndThrow(AssertionFailureBuilder.java:132)
	at org.junit.jupiter.api.AssertTrue.failNotTrue(AssertTrue.java:63)
	at org.junit.jupiter.api.AssertTrue.assertTrue(AssertTrue.java:36)
...

Report flaky test

keycloak-github-bot · 2026-07-13T17:18:58Z

Unreported flaky test detected

If the flaky tests below are affected by the changes, please review and update the changes accordingly. Otherwise, a maintainer should report the flaky tests prior to merging the PR.

org.keycloak.testsuite.adapter.servlet.SAMLServletAdapterTest#salesPostSigPersistentTest

Keycloak CI - Adapter IT Strict Cookies

org.opentest4j.AssertionFailedError: expected: <true> but was: <false>
	at org.junit.jupiter.api.AssertionFailureBuilder.build(AssertionFailureBuilder.java:151)
	at org.junit.jupiter.api.AssertionFailureBuilder.buildAndThrow(AssertionFailureBuilder.java:132)
	at org.junit.jupiter.api.AssertTrue.failNotTrue(AssertTrue.java:63)
	at org.junit.jupiter.api.AssertTrue.assertTrue(AssertTrue.java:36)
...

Report flaky test

org.keycloak.testsuite.adapter.servlet.SAMLServletAdapterTest#salesMetadataTest

Keycloak CI - Adapter IT Strict Cookies

org.opentest4j.AssertionFailedError: expected: <true> but was: <false>
	at org.junit.jupiter.api.AssertionFailureBuilder.build(AssertionFailureBuilder.java:151)
	at org.junit.jupiter.api.AssertionFailureBuilder.buildAndThrow(AssertionFailureBuilder.java:132)
	at org.junit.jupiter.api.AssertTrue.failNotTrue(AssertTrue.java:63)
	at org.junit.jupiter.api.AssertTrue.assertTrue(AssertTrue.java:36)
...

Report flaky test

org.keycloak.testsuite.adapter.servlet.SAMLServletAdapterTest#employeeSigPostNoIdpKeyTestNoKeyNameInKeyInfo

Keycloak CI - Adapter IT Strict Cookies

org.opentest4j.AssertionFailedError: expected: <true> but was: <false>
	at org.junit.jupiter.api.AssertionFailureBuilder.build(AssertionFailureBuilder.java:151)
	at org.junit.jupiter.api.AssertionFailureBuilder.buildAndThrow(AssertionFailureBuilder.java:132)
	at org.junit.jupiter.api.AssertTrue.failNotTrue(AssertTrue.java:63)
	at org.junit.jupiter.api.AssertTrue.assertTrue(AssertTrue.java:36)
...

Report flaky test

org.keycloak.testsuite.adapter.servlet.SAMLServletAdapterTest#salesPostEncTest

Keycloak CI - Adapter IT Strict Cookies

org.opentest4j.AssertionFailedError: expected: <true> but was: <false>
	at org.junit.jupiter.api.AssertionFailureBuilder.build(AssertionFailureBuilder.java:151)
	at org.junit.jupiter.api.AssertionFailureBuilder.buildAndThrow(AssertionFailureBuilder.java:132)
	at org.junit.jupiter.api.AssertTrue.failNotTrue(AssertTrue.java:63)
	at org.junit.jupiter.api.AssertTrue.assertTrue(AssertTrue.java:36)
...

Report flaky test

keycloak-github-bot

Unreported flaky test detected, please review

Copilot

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.

Copilot

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 3 comments.

Copilot

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated 6 comments.

Copilot

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated 2 comments.

Copilot

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated no new comments.

rmartinc

Thanks @uzmamansoor09! Looks good but I think we can improve the situation more:

Adding the option to pass parameters to the messages (for example to show the invalid aaguid or the invalid attachment). We can even add the original webauthn message for some of them if we consider necessary to ad the details. But for the moment it's OK. I just want to have the ability to use parameters.
Catching the ModelDuplicateException in the registration class and creating another specific error for the duplcate device as before.
I think we can remove a lot of the warning messages you are adding because the event is already showing the previous detailed message. You can remove or change to debug all of them.

I have create a new commit named test in this branch: https://github.com/rmartinc/keycloak/tree/refs/heads/pr-50654 (I'm passing the CI now in GitHub, but locally the webauthn jobs passed OK). You can cherry-pick this commit and tune or change it as you want. I wanted to test if we can pass parameters to improve the messages. This gives us more freedom to create better messages for the future if needed.

mabartos · 2026-07-20T12:52:08Z

Hi! Would be also good to check this PR that also improves the error message and provides the i18n ability: #51012

It'd be good to think about the possibility of localizing the messages and decide whether the PR should be a follow-up, or it should somehow influence this PR. Thanks!

I'll do the actual review later.

Signed-off-by: uzmamansoor09 <Uzma.Mansoor@ibm.com> # Conflicts: # testsuite/integration-arquillian/tests/base/src/test/java/org/keycloak/testsuite/webauthn/WebAuthnIdlessTest.java # testsuite/integration-arquillian/tests/base/src/test/java/org/keycloak/testsuite/webauthn/registration/AttestationConveyanceRegisterTest.java # testsuite/integration-arquillian/tests/base/src/test/java/org/keycloak/testsuite/webauthn/registration/AuthAttachmentRegisterTest.java

Signed-off-by: uzmamansoor09 <Uzma.Mansoor@ibm.com>

keycloak-github-bot

Unreported flaky test detected, please review

keycloak-github-bot · 2026-07-23T18:36:51Z

Unreported flaky test detected

If the flaky tests below are affected by the changes, please review and update the changes accordingly. Otherwise, a maintainer should report the flaky tests prior to merging the PR.

org.keycloak.testsuite.forms.MultipleTabsLoginTest#testLoginPageRefresh

Keycloak CI - Forms IT (firefox)

org.opentest4j.AssertionFailedError: expected: <true> but was: <false>
	at org.junit.jupiter.api.AssertionFailureBuilder.build(AssertionFailureBuilder.java:151)
	at org.junit.jupiter.api.AssertionFailureBuilder.buildAndThrow(AssertionFailureBuilder.java:132)
	at org.junit.jupiter.api.AssertTrue.failNotTrue(AssertTrue.java:63)
	at org.junit.jupiter.api.AssertTrue.assertTrue(AssertTrue.java:36)
...

Report flaky test

rmartinc

Thanks @uzmamansoor09! As we chatted the issue #44963 will be managed as a follow-up. We can use the webauthn4j exception thrown in the authentication and registration to give a different message per exception (or just the most commons exceptions). Approving and merging this one for the moment.

rmartinc · 2026-07-24T09:08:33Z

            result = user.credentialManager().isValid(cred);
        } catch (WebAuthnException wae) {
+            logger.debug("WebAuthn authentication verification failed.", wae);
            setErrorResponse(context, WEBAUTHN_ERROR_AUTH_VERIFICATION, wae.getMessage());


As commented by Martin and in #44963, here we can use the WebAuthnException type to give detailed messages (maybe not all of them, but the common ones). But #44963 will be managed as a follow-up.

rmartinc · 2026-07-24T09:12:03Z

        } catch (WebAuthnException wae) {
-            if (logger.isDebugEnabled()) logger.debug(wae.getMessage(), wae);
+            logger.debug("WebAuthn registration failed.", wae);
            setErrorResponse(context, WEBAUTHN_ERROR_REGISTRATION, wae.getMessage(), originalEventType);


Same here, the WebAuthnExceptioncan be used to set a more detailed message instead of the generic one. But there will be another PR for that.

keycloak-github-bot Bot added the team/core-authn label Jul 7, 2026

uzmamansoor09 requested a review from Copilot July 8, 2026 09:26

Copilot started reviewing on behalf of uzmamansoor09 July 8, 2026 09:27 View session

Copilot AI reviewed Jul 8, 2026

View reviewed changes

Comment thread services/src/main/java/org/keycloak/authentication/requiredactions/WebAuthnRegister.java

uzmamansoor09 force-pushed the 22524 branch from d6ed631 to abe406d Compare July 8, 2026 09:43

keycloak-github-bot Bot added the flaky-test label Jul 8, 2026

keycloak-github-bot Bot reviewed Jul 8, 2026

View reviewed changes

uzmamansoor09 force-pushed the 22524 branch 5 times, most recently from 874903d to a4f9dfd Compare July 13, 2026 16:04

keycloak-github-bot Bot reviewed Jul 13, 2026

View reviewed changes

uzmamansoor09 force-pushed the 22524 branch 2 times, most recently from 57852b3 to b07000e Compare July 13, 2026 21:14

uzmamansoor09 marked this pull request as ready for review July 14, 2026 08:47

uzmamansoor09 requested a review from a team as a code owner July 14, 2026 08:47

Copilot AI review requested due to automatic review settings July 14, 2026 08:47

uzmamansoor09 requested review from a team as code owners July 14, 2026 08:47

Copilot started reviewing on behalf of uzmamansoor09 July 14, 2026 08:48 View session

Copilot AI reviewed Jul 14, 2026

View reviewed changes

Comment thread ...e/src/test/java/org/keycloak/testsuite/webauthn/registration/AuthAttachmentRegisterTest.java Outdated

Comment thread services/src/main/java/org/keycloak/authentication/requiredactions/WebAuthnRegister.java Outdated

Copilot AI review requested due to automatic review settings July 14, 2026 08:53

Copilot started reviewing on behalf of uzmamansoor09 July 14, 2026 08:55 View session

Copilot AI reviewed Jul 14, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings July 15, 2026 16:36

Copilot started reviewing on behalf of uzmamansoor09 July 15, 2026 16:37 View session

Copilot AI reviewed Jul 15, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings July 15, 2026 19:05

uzmamansoor09 force-pushed the 22524 branch from 9e91467 to daca97d Compare July 15, 2026 19:05

Copilot started reviewing on behalf of uzmamansoor09 July 15, 2026 19:05 View session

Copilot AI reviewed Jul 15, 2026

View reviewed changes

Comment thread .../src/main/java/org/keycloak/authentication/authenticators/browser/WebAuthnAuthenticator.java Outdated

Comment thread services/src/main/java/org/keycloak/authentication/requiredactions/WebAuthnRegister.java

uzmamansoor09 marked this pull request as draft July 15, 2026 19:15

uzmamansoor09 force-pushed the 22524 branch 2 times, most recently from 146eba1 to bcee042 Compare July 15, 2026 19:29

uzmamansoor09 marked this pull request as ready for review July 15, 2026 19:29

Copilot AI review requested due to automatic review settings July 15, 2026 19:29

Copilot started reviewing on behalf of uzmamansoor09 July 15, 2026 19:30 View session

Copilot AI reviewed Jul 15, 2026

View reviewed changes

rmartinc requested changes Jul 17, 2026

View reviewed changes

uzmamansoor09 added 2 commits July 23, 2026 18:31

Following review

77f3bee

Signed-off-by: uzmamansoor09 <Uzma.Mansoor@ibm.com>

uzmamansoor09 force-pushed the 22524 branch from a685134 to 77f3bee Compare July 23, 2026 17:36

keycloak-github-bot Bot reviewed Jul 23, 2026

View reviewed changes

rmartinc approved these changes Jul 24, 2026

View reviewed changes

rmartinc merged commit 2bbce40 into keycloak:main Jul 24, 2026
91 checks passed

Uh oh!

Conversation

uzmamansoor09 commented Jul 7, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

keycloak-github-bot Bot left a comment

Choose a reason for hiding this comment

Uh oh!

keycloak-github-bot Bot commented Jul 8, 2026

Unreported flaky test detected

org.keycloak.testsuite.forms.BruteForceTest#testExceedMaxTemporaryLockouts

Uh oh!

keycloak-github-bot Bot commented Jul 13, 2026

Unreported flaky test detected

org.keycloak.testsuite.adapter.servlet.SAMLServletAdapterTest#salesPostSigPersistentTest

org.keycloak.testsuite.adapter.servlet.SAMLServletAdapterTest#salesMetadataTest

org.keycloak.testsuite.adapter.servlet.SAMLServletAdapterTest#employeeSigPostNoIdpKeyTestNoKeyNameInKeyInfo

org.keycloak.testsuite.adapter.servlet.SAMLServletAdapterTest#salesPostEncTest

Uh oh!

keycloak-github-bot Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

rmartinc left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mabartos commented Jul 20, 2026

Uh oh!

keycloak-github-bot Bot left a comment

Choose a reason for hiding this comment

Uh oh!

keycloak-github-bot Bot commented Jul 23, 2026

Unreported flaky test detected

org.keycloak.testsuite.forms.MultipleTabsLoginTest#testLoginPageRefresh

Uh oh!

rmartinc left a comment