{"record":{"id":"d6787a4fbd848c82","repo":"apereo/cas","slug":"authentication-handler-is-disabled","errorCode":null,"errorMessage":"Authentication handler is disabled","messagePattern":"Authentication handler is disabled","errorType":"exception","errorClass":"PreventedException","httpStatus":null,"severity":"error","filePath":"api/cas-server-core-api-authentication/src/main/java/org/apereo/cas/authentication/AuthenticationHandler.java","lineNumber":35,"sourceCode":" * @author Marvin S. Addison\n * @since 4.0.0\n */\n@FunctionalInterface\npublic interface AuthenticationHandler extends Ordered, NamedObject {\n\n    /**\n     * Attribute name containing collection of handler names that successfully authenticated credential.\n     */\n    String SUCCESSFUL_AUTHENTICATION_HANDLERS = \"successfulAuthenticationHandlers\";\n\n    /**\n     * Disabled authentication handler.\n     *\n     * @return the authentication handler\n     */\n    static AuthenticationHandler disabled() {\n        return (credential, service) -> {\n            throw new PreventedException(\"Authentication handler is disabled\");\n        };\n    }\n\n    /**\n     * Authenticates the given credential. There are three possible outcomes of this process, and implementers\n     * MUST adhere to the following contract:\n     *\n     * <ol>\n     * <li>Success -- return {@link AuthenticationHandlerExecutionResult}</li>\n     * <li>Failure -- throw {@link GeneralSecurityException}</li>\n     * <li>Indeterminate -- throw {@link PreventedException}</li>\n     * </ol>\n     *\n     * @param credential The credential to authenticate.\n     * @param service    the requesting service, if any.\n     * @return A result object containing metadata about a successful authentication event that includes at a\n     * minimum the name of the handler that authenticated the credential and some credential metadata. The following data\n     * is optional: <ul> <li>{@link Principal}</li> <li>Messages issued by the handler about the credential (e.g. impending password expiration warning)</li> </ul>","sourceCodeStart":17,"sourceCodeEnd":53,"githubUrl":"https://github.com/apereo/cas/blob/e7288fc434b4f4505b8452e1a57e8fb3111bb863/api/cas-server-core-api-authentication/src/main/java/org/apereo/cas/authentication/AuthenticationHandler.java#L17-L53","documentation":"AuthenticationHandler.disabled() returns a placeholder handler whose authenticate() immediately throws PreventedException('Authentication handler is disabled'). It is a no-op used when a handler type is configured but its feature is disabled, guaranteeing it never authenticates credentials.","triggerScenarios":"A handler bean registered as AuthenticationHandler.disabled() receives a credential during an authentication transaction, typically because the real module/feature is disabled via @ConditionalOnFeatureEnabled or a missing dependency.","commonSituations":"CAS module owning the real handler not on the classpath, feature flag off, or custom code explicitly wiring the disabled stub instead of a real handler.","solutions":["Enable the authentication feature/module that supplies the real handler (add dependency or enable feature flag)","Remove the disabled handler from the execution plan so other handlers can support the credential","Inspect configuration/logs to find why the real handler was replaced by the disabled stub"],"exampleFix":"// before\nAuthenticationHandler handler = AuthenticationHandler.disabled();\n// after\nAuthenticationHandler handler = new MyLdapAuthenticationHandler(ldapAuthenticator, servicesManager);","handlingStrategy":"validation","validationCode":"// before authenticating, ensure the handler is not the disabled stub\nif (handler == AuthenticationHandler.disabled()) {\n    throw new IllegalStateException(\"Handler feature is disabled; enable its module/feature flag\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    AuthenticationResult r = transactionManager.authenticate(transaction);\n} catch (PreventedException e) {\n    if (\"Authentication handler is disabled\".equals(e.getMessage())) {\n        LOGGER.error(\"Feature-disabled handler used; enable the owning module\");\n    }\n}","preventionTips":["Enable the CAS module/feature that supplies the real handler","Do not wire AuthenticationHandler.disabled() in production configs","Audit the authentication execution plan at startup for disabled handlers"],"tags":["java","authentication","disabled-handler"],"backgroundTag":"feature-not-enabled","analyzedSha":"e7288fc434b4f4505b8452e1a57e8fb3111bb863","analyzedAt":"2026-09-08T15:39:16.015Z","contentChangedAt":"2026-09-08T15:39:16.015Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}