fix(auth): prevent 2FA bypass when user lacks required role in alternative flows

Author: kidager

README.md

@@ -106,6 +106,17 @@ The authenticator is built and tested with multiple Keycloak versions:
 While the builds differ slightly for each version, the core functionality remains the same. The version-specific builds ensure compatibility and proper integration with each Keycloak release.
 
 
+## Known Limitations
+
+### Email OTP appears in "Try Another Way" for users without the required role
+
+When using role-based filtering in an ALTERNATIVE flow alongside other 2FA methods (e.g., TOTP), Email OTP may still appear in Keycloak's "Try another way" selection list for users who don't have the required role. This is a Keycloak architectural limitation - the selection list is built using a different code path that doesn't fully respect our role filtering.
+
+**Important:** Selecting Email OTP in this case will **not** bypass 2FA. The user will be redirected back to complete their other configured 2FA method (e.g., TOTP).
+
+**Workaround:** If you need to completely hide Email OTP for certain users, use Keycloak's built-in **Condition - User Role** execution in a conditional subflow instead of the authenticator's role filtering option.
+
+
 ## License
 
 This project is released under the [Unlicense](./UNLICENSE). This means you can copy, modify, publish, use, compile, sell, or distribute this software, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means.

src/main/java/ch/jacem/for_keycloak/email_otp_authenticator/EmailOTPFormAuthenticator.java

@@ -15,6 +15,8 @@
 import org.keycloak.email.EmailTemplateProvider;
 import org.keycloak.events.Errors;
 import org.keycloak.forms.login.LoginFormsProvider;
+import org.keycloak.models.AuthenticationExecutionModel;
+import org.keycloak.models.AuthenticationFlowModel;
 import org.keycloak.models.AuthenticatorConfigModel;
 import org.keycloak.models.KeycloakSession;
 import org.keycloak.models.RealmModel;
@@ -123,9 +125,15 @@ public void action(AuthenticationFlowContext context) {
 
     @Override
     public void authenticate(AuthenticationFlowContext context) {
-        // Check role condition - skip OTP if user doesn't match criteria
+        // Check role condition - if user doesn't match criteria, skip this authenticator
         if (!this.shouldRequireOtp(context)) {
-            context.success();
+            // In REQUIRED mode: use success() to skip (allows role-based filtering)
+            // In ALTERNATIVE mode: use attempted() to prevent 2FA bypass
+            if (context.getExecution().isRequired()) {
+                context.success();
+            } else {
+                context.attempted();
+            }
             return;
         }
 
@@ -192,7 +200,78 @@ public boolean configuredFor(AuthenticationFlowContext context, AuthenticatorCon
 
     @Override
     public boolean configuredFor(KeycloakSession session, RealmModel realm, UserModel user) {
-        return null != user.getEmail() && !user.getEmail().isEmpty();
+        if (user == null || user.getEmail() == null || user.getEmail().isEmpty()) {
+            logger.debugf("configuredFor: user is null or has no email");
+            return false;
+        }
+
+        // Check all authentication flows for email-otp-form executions (including nested subflows)
+        // Return true only if user matches at least one execution's role requirement
+        for (AuthenticationFlowModel flow : realm.getAuthenticationFlowsStream().toList()) {
+            logger.debugf("configuredFor: checking flow %s", flow.getAlias());
+            if (isUserConfiguredForEmailOtpInFlow(realm, user, flow.getId())) {
+                logger.debugf("configuredFor: user %s is configured for email-otp in flow %s", user.getUsername(), flow.getAlias());
+                return true;
+            }
+        }
+
+        // User doesn't match any email-otp-form execution's requirements
+        logger.debugf("configuredFor: user %s is NOT configured for any email-otp execution", user.getUsername());
+        return false;
+    }
+
+    private boolean isUserConfiguredForEmailOtpInFlow(RealmModel realm, UserModel user, String flowId) {
+        for (AuthenticationExecutionModel execution : realm.getAuthenticationExecutionsStream(flowId).toList()) {
+            // If this is a subflow, recursively check it
+            if (execution.isAuthenticatorFlow()) {
+                String subflowId = execution.getFlowId();
+                if (subflowId != null && isUserConfiguredForEmailOtpInFlow(realm, user, subflowId)) {
+                    return true;
+                }
+                continue;
+            }
+
+            // Check if this is an email-otp-form execution
+            if (!EmailOTPFormAuthenticatorFactory.PROVIDER_ID.equals(execution.getAuthenticator())) {
+                continue;
+            }
+
+            // Get the config for this execution
+            String configId = execution.getAuthenticatorConfig();
+            if (configId == null) {
+                // No config means no role restriction - user is eligible
+                return true;
+            }
+
+            AuthenticatorConfigModel config = realm.getAuthenticatorConfigById(configId);
+            if (config == null) {
+                // Config not found, treat as no restriction
+                return true;
+            }
+
+            // Check role requirement
+            String configuredRole = ConfigHelper.getRole(config);
+            if (configuredRole == null || configuredRole.isEmpty()) {
+                // No role configured - user is eligible
+                return true;
+            }
+
+            RoleModel role = realm.getRole(configuredRole);
+            if (role == null) {
+                // Role doesn't exist - treat as no restriction
+                return true;
+            }
+
+            // Check if user matches the role requirement (considering negation)
+            boolean hasRole = user.hasRole(role);
+            boolean negateRole = ConfigHelper.getNegateRole(config);
+            if (hasRole != negateRole) {
+                // User matches this execution's requirement
+                return true;
+            }
+        }
+
+        return false;
     }
 
     @Override

tests/e2e/helpers/otp-form.ts

@@ -102,4 +102,29 @@ export class TwoFactorChoice {
       }
     }
   }
+
+  async isEmailOtpOptionVisible(): Promise<boolean> {
+    // Check specifically for Email OTP in the authentication method selection list
+    // Keycloak shows options as clickable divs/links with the authenticator display name
+    const selectors = [
+      '.select-auth-box-parent:has-text("Email OTP")',
+      '.select-auth-box-desc:has-text("Email")',
+      '#kc-select-credential-form :has-text("Email OTP")',
+      'a[id*="email-otp"]',
+      'div.pf-c-tile:has-text("Email")',
+    ];
+
+    for (const selector of selectors) {
+      const element = this.page.locator(selector).first();
+      if (await element.isVisible({ timeout: 1000 }).catch(() => false)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  async isTryAnotherWayVisible(): Promise<boolean> {
+    const tryAnotherLink = this.page.locator('a:has-text("Try another way"), a:has-text("try another way"), #try-another-way');
+    return await tryAnotherLink.isVisible({ timeout: 2000 }).catch(() => false);
+  }
 }

tests/e2e/specs/otp-alternative.spec.ts

@@ -69,6 +69,53 @@ test.describe('Email OTP Alternative Flow', () => {
       await loginPage.expectLoggedIn();
     });
 
+    test('user without role, has TOTP - selecting Email OTP does not bypass 2FA', async ({ page }) => {
+      const loginPage = new LoginPage(page);
+      const totpForm = new TotpForm(page);
+      const choice = new TwoFactorChoice(page);
+
+      await loginPage.goto(REALM);
+      await loginPage.login('user-totp-only', TEST_PASSWORD);
+
+      // Should see TOTP form
+      await totpForm.expectVisible();
+
+      // If "Try another way" is visible, try selecting Email OTP
+      const hasTryAnotherWay = await choice.isTryAnotherWayVisible();
+      if (hasTryAnotherWay) {
+        await choice.clickTryAnotherWay();
+        await page.waitForTimeout(500);
+
+        // Try to select Email OTP (if visible)
+        const emailOtpOption = page.locator('text="Email OTP"').first();
+        if (await emailOtpOption.isVisible({ timeout: 1000 }).catch(() => false)) {
+          await emailOtpOption.click();
+          await page.waitForLoadState('networkidle');
+
+          // User should NOT be logged in - should still be on a 2FA page
+          // The flow should either show an error or redirect back to TOTP
+          const isLoggedIn = await page.url().includes('/account') ||
+            await page.locator('text="Sign out"').isVisible({ timeout: 1000 }).catch(() => false);
+          expect(isLoggedIn).toBe(false);
+
+          // Should be back on TOTP form or still in auth flow
+          const onAuthPage = await page.url().includes('/login-actions') ||
+            await totpForm.expectVisible().then(() => true).catch(() => false);
+          expect(onAuthPage).toBe(true);
+        }
+      }
+
+      // Complete TOTP login normally
+      // First go back if needed
+      if (!await page.locator('#otp').isVisible({ timeout: 1000 }).catch(() => false)) {
+        await page.goBack();
+      }
+      await totpForm.expectVisible();
+      const totpCode = generateTotpCode('user-totp-only');
+      await totpForm.enterCode(totpCode);
+      await loginPage.expectLoggedIn();
+    });
+
     test('user with role, no TOTP - sees Email OTP', async ({ page }) => {
       const loginPage = new LoginPage(page);
       const otpForm = new OtpForm(page);