Sign-in protection & reCAPTCHA

What is protected

When configured by your installation operator, Google reCAPTCHA v3 checks password sign-in and anonymous password-reset requests on the identity service. It works in the background without an image puzzle. Reset protection applies only if password recovery is enabled.

Existing SSO sessions, enterprise identity providers and passkeys retain their native authentication policies. CAPTCHA supplements MFA, password policy and rate limiting. It is not required for ordinary authenticated course activity or service APIs.

Operator setup

1. Create a Google reCAPTCHA v3 key and register the authentication hostname. Use separate keys for development and production where possible.
2. Build and package the version-matched ZubLMS authenticator provider and login theme in Keycloak. The current provider targets Keycloak 26.4.5; repeat authentication acceptance when upgrading.
3. Configure the public site key, private secret file, exact hostname allowlist and minimum score in the identity process. Keep secrets out of browser environment variables and source control.
4. Copy the existing browser and recovery flows and replace the credential/reset-user steps with the protected authenticators. Preserve MFA, IdP routing and existing account data. Disable direct password grants on all clients in the protected realm, including built-in clients, and inspect client-specific flow overrides. Keep restricted operator administration separate.
5. Test real sign-in on a staged client before binding the protected flows. Verify missing-token rejection, valid login, retry, reset, responsive layout and a recovery plan. Keep the original flow bindings available for a deliberate operator rollback.

RECAPTCHA_SITE_KEY_FILE=/run/secrets/recaptcha-site-key
RECAPTCHA_SECRET_KEY_FILE=/run/secrets/recaptcha-secret-key
RECAPTCHA_ALLOWED_HOSTNAMES=auth.your-domain.example
RECAPTCHA_MIN_SCORE=0.5

Verification and troubleshooting

Verification runs inside Keycloak before password checks or anonymous recovery dispatch. It checks Google's success, score, action, hostname and token age. A fresh token is obtained on every submission; expired, reused, missing and rejected challenges cannot establish a password sign-in.

Google or network failures deny protected requests. Retry, check content blocking and contact your administrator if the message persists. Operators should check registered domains, key pairing, server time, connectivity and Google score distributions. Automated headless tests can receive low scores; do not lower the threshold just to make tests pass.

There is no company-level secret editor for this installation-wide setting. Operators use private identity configuration and a controlled rollout. A local setup does not automatically enable it in production.

Privacy and scope

Google's script loads only on protected sign-in and recovery forms. Google receives browser security signals and may use its own cookies under its policies. The form shows its privacy and terms links. The LMS does not send passwords or course content in the server verification request.

This security integration is separate from optional analytics and marketing destinations. Each operator must review its provider inventory and applicable privacy requirements. Registration and any future anonymous backend contact form need their own protection before enablement.