{"record":{"id":"3b23d7d7a0d2dc5c","repo":"apereo/cas","slug":"configuration-specifies-checkkeyusage-but-keyusage","errorCode":null,"errorMessage":"Configuration specifies checkKeyUsage but keyUsage extension not found in certificate.","messagePattern":"Configuration specifies checkKeyUsage but keyUsage extension not found in certificate\\.","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"support/cas-server-support-x509-core/src/main/java/org/apereo/cas/adaptors/x509/authentication/handler/support/X509CredentialsAuthenticationHandler.java","lineNumber":272,"sourceCode":"                throw new FailedLoginException(msg);\n            }\n        }\n    }\n\n    /**\n     * Checks if is valid key usage. <p>\n     * KeyUsage ::= BIT STRING { digitalSignature (0), nonRepudiation (1),\n     * keyEncipherment (2), dataEncipherment (3), keyAgreement (4),\n     * keyCertSign (5), cRLSign (6), encipherOnly (7), decipherOnly (8) }\n     *\n     * @param certificate the certificate\n     * @return true, if  valid key usage\n     */\n    private boolean isValidKeyUsage(final X509Certificate certificate) {\n        LOGGER.debug(\"Checking certificate keyUsage extension\");\n        val keyUsage = certificate.getKeyUsage();\n        if (keyUsage == null) {\n            LOGGER.warn(\"Configuration specifies checkKeyUsage but keyUsage extension not found in certificate.\");\n            return !this.requireKeyUsage;\n        }\n\n        val func = FunctionUtils.doIf(c -> isCritical(certificate, KEY_USAGE_OID) || requireKeyUsage,\n            t -> {\n                LOGGER.debug(\"KeyUsage extension is marked critical or required by configuration.\");\n                return keyUsage[0];\n            },\n            f -> {\n                LOGGER.debug(\"KeyUsage digitalSignature=%s, Returning true since keyUsage validation not required by configuration.\");\n                return Boolean.TRUE;\n            });\n        return func.apply(certificate);\n    }\n\n    /**\n     * Checks if is certificate allowed based no the pattern given.\n     *","sourceCodeStart":254,"sourceCodeEnd":290,"githubUrl":"https://github.com/apereo/cas/blob/e7288fc434b4f4505b8452e1a57e8fb3111bb863/support/cas-server-support-x509-core/src/main/java/org/apereo/cas/adaptors/x509/authentication/handler/support/X509CredentialsAuthenticationHandler.java#L254-L290","documentation":"The handler is configured to check the keyUsage extension (checkKeyUsage=true) but the presented certificate contains no keyUsage extension at all. isValidKeyUsage logs this warning and returns !requireKeyUsage, meaning the certificate is rejected only when keyUsage is also marked as required; otherwise validation continues despite the missing extension.","triggerScenarios":"validate() calls isValidKeyUsage() during certificate validation; certificate.getKeyUsage() returns null because the certificate was issued without a keyUsage extension while cas.authn.x509 check-key-usage is enabled in configuration.","commonSituations":"CA issues certificates without the keyUsage extension (common with some client/certificate templates); operator enables checkKeyUsage based on documentation without knowing their CA's certificate profiles; migration between CAs with different certificate templates.","solutions":["If your certificates intentionally lack keyUsage, either disable the check (set check-key-usage=false) or keep require-key-usage=false so missing extensions are tolerated.","Re-issue the client certificate with a template/profile that includes the keyUsage extension (best long-term fix).","If the extension must exist and be valid, leave require-key-usage=true and have your CA issue certificates with keyUsage; certificates without it will be rejected as expected.","Inspect the failing certificate (openssl x509 -text) to confirm keyUsage is truly absent before changing configuration."],"exampleFix":"// before\ncas.authn.x509.check-key-usage=true\ncas.authn.x509.require-key-usage=true\n// after (certificates without keyUsage are accepted)\ncas.authn.x509.check-key-usage=true\ncas.authn.x509.require-key-usage=false","handlingStrategy":"validation","validationCode":"// Check the certificate before validation:\nval keyUsage = certificate.getKeyUsage();\nif (keyUsage == null && requireKeyUsage) {\n    logger.warn(\"Certificate {} lacks keyUsage but it is required; will be rejected\", certificate.getSerialNumber());\n}","typeGuard":null,"tryCatchPattern":"try {\n    handler.authenticate(x509Credential);\n} catch (FailedLoginException e) {\n    if (certificate.getKeyUsage() == null) {\n        logger.warn(\"Certificate has no keyUsage extension; relax require-key-usage or reissue cert\");\n    }\n    throw e;\n}","preventionTips":["Audit your CA's certificate templates to confirm keyUsage is present before enabling checkKeyUsage.","Prefer requiring keyUsage=true only when you control certificate issuance.","Inspect client certificates with openssl x509 -text when diagnosing X.509 auth failures.","Document the intended combination of check-key-usage and require-key-usage for operators."],"tags":["x509","key-usage","certificate-validation"],"backgroundTag":"invalid-config-value","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"}