{"record":{"id":"076630e7ab7272b6","repo":"apereo/cas","slug":"certificate-keyusage-constraint-forbids-ssl-client","errorCode":null,"errorMessage":"Certificate keyUsage constraint forbids SSL client authentication.","messagePattern":"Certificate keyUsage constraint forbids SSL client authentication\\.","errorType":"exception","errorClass":"FailedLoginException","httpStatus":null,"severity":"error","filePath":"support/cas-server-support-x509-core/src/main/java/org/apereo/cas/adaptors/x509/authentication/handler/support/X509CredentialsAuthenticationHandler.java","lineNumber":243,"sourceCode":"        LOGGER.warn(\"Either client certificate could not be determined, or a trusted issuer could not be located\");\n        throw new FailedLoginException();\n    }\n\n    private void validate(final X509Certificate cert) throws GeneralSecurityException {\n        cert.checkValidity();\n        this.revocationChecker.check(cert);\n\n        val pathLength = cert.getBasicConstraints();\n        if (pathLength < 0) {\n            if (!isCertificateAllowed(cert)) {\n                val msg = \"Certificate subject does not match pattern \" + this.regExSubjectDnPattern.pattern();\n                LOGGER.error(msg);\n                throw new FailedLoginException(msg);\n            }\n            if (this.checkKeyUsage && !isValidKeyUsage(cert)) {\n                val msg = \"Certificate keyUsage constraint forbids SSL client authentication.\";\n                LOGGER.error(msg);\n                throw new FailedLoginException(msg);\n            }\n        } else {\n            if (pathLength == Integer.MAX_VALUE && !this.maxPathLengthAllowUnspecified) {\n                val msg = \"Unlimited certificate path length not allowed by configuration.\";\n                LOGGER.error(msg);\n                throw new FailedLoginException(msg);\n            }\n            if (pathLength > this.maxPathLength && pathLength < Integer.MAX_VALUE) {\n                val msg = String.format(\"Certificate path length %s exceeds maximum value %s.\", pathLength, this.maxPathLength);\n                LOGGER.error(msg);\n                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),","sourceCodeStart":225,"sourceCodeEnd":261,"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#L225-L261","documentation":"When checkKeyUsage is enabled, X509CredentialsAuthenticationHandler.validate() verifies that an end-entity certificate's keyUsage extension permits SSL/TLS client authentication. If isValidKeyUsage() finds the required bits absent (or the extension missing), it throws FailedLoginException.","triggerScenarios":"cas.authn.x509.check-key-usage=true and the presented end-entity certificate's keyUsage bits do not satisfy the client-auth requirement (e.g. no digitalSignature/keyEncipherment bits).","commonSituations":"Certificates issued for serverAuth or code signing used as client certs; PKI re-issue dropping the digitalSignature bit; checkKeyUsage enabled while the CA issues certs without any keyUsage extension.","solutions":["Set cas.authn.x509.check-key-usage=false if your PKI does not populate keyUsage for client certs.","Re-issue the client certificate with keyUsage including digitalSignature (plus keyEncipherment as appropriate for TLS client auth).","Use a certificate explicitly issued for client authentication.","Inspect the cert with: openssl x509 -in cert.pem -noout -ext keyUsage."],"exampleFix":"// before\ncas.authn.x509.check-key-usage=true\n// after\ncas.authn.x509.check-key-usage=false","handlingStrategy":"validation","validationCode":"boolean[] ku = cert.getKeyUsage();\nboolean ok = ku != null && ((ku[0] /* digitalSignature */));\nif (!ok) { reject(\"cert not usable for client auth\"); }","typeGuard":"boolean supportsClientAuth(X509Certificate cert) {\n    boolean[] ku = cert.getKeyUsage();\n    return ku != null && ku.length > 0 && ku[0];\n}","tryCatchPattern":"try {\n    handler.authenticate(credential);\n} catch (FailedLoginException e) {\n    // keyUsage forbids client authentication: re-issue cert or relax checkKeyUsage\n}","preventionTips":["Issue client certificates with digitalSignature (and keyEncipherment) keyUsage bits.","Only enable check-key-usage if the PKI reliably populates keyUsage.","Inspect certs with openssl x509 -ext keyUsage before enrollment.","Document required keyUsage in your certificate policy."],"tags":["x509","certificate","keyusage","authentication"],"backgroundTag":"certificate-key-usage-rejected","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"}