If you are experiencing issues with the Certificate Authentication module, you can try these troubleshooting steps to find and resolve the issue:
- Check that you have met all the prerequisites; in particular ensure the com.sun.security.enableCRLDP option is set to true if you are doing CRL checking. See How do I configure certificate-based authentication in AM (All versions)? for further information.
- Check that you can successfully authenticate with your certificate using curl to help isolate if the certificate is causing an issue.
- Replicate the search that the Certificate Authentication module is doing in your LDAP directory to check that you can find the user using your configuration and that they have a valid certificate entry.
- Collect logs and check the Common errors section for further information about errors you find along with possible solutions:
- Collect message level debug logs as detailed in Debug logging (AM 7 and later) or How do I enable Message level debugging in AM 6.x debug files? The CoreSystem and Authentication debug logs are the most useful ones for troubleshooting the Certificate Authentication module. You can also use the recording tool to collect these logs: How do I record troubleshooting information in AM (All versions)?
- Enable certificate related debug options in your web application container to help identify any specific certificate related failures and then collect these logs (for example, catalina.out on Apache Tomcat™).
- Collect access logs from your LDAP server and check there are no connection issues. See How do I use the Access log to troubleshoot DS (All versions)? for further information if you are using DS.
- Use one of the third-party certificate management tools that are available to aid examining and resolving issues with keystores and certificates. One of the preferred tools is Keystore Explorer (a free open source GUI replacement for the Java® command-line utilities keytool and jarsigner). This application provides an intuitive interface with multiple features that simplify keystore and certificate management. This is a third-party tool that we suggest can be used but is not supported by ForgeRock.
The following section provides some positive progress messages you will see in the logs so you know which stages are completing. In conjunction with the other troubleshooting tips, this should help you narrow down where the failure is occurring.
|AMCertPath.verify: crlEnabled ---> true||Indicates the JAVA API is configured for CRL checking, that is, com.sun.security.enableCRLDP has been set to true.|
|Got client cert = [ [ <certificate detail> ]||Indicates AM has successfully retrieved the certificate.|
|Cert.doRevocationValidation: crls size = 0||Indicates AM is performing the CRL checks.|
|CertPath:verify success.||Indicates a successful CRL check.|
You can use the following curl command to check that you can authenticate using your certificate; the -v option is included for a verbose output to aid troubleshooting: $ curl -v -X POST -H "Accept-API-Version: resource=2.1" "https://www.am.example.com:8443/am/json/realms/root/authenticate?authIndexType=module&authIndexValue=[moduleName]" --cert [clientchain.pem]
Replacing [moduleName] and [clientchain.pem] with appropriate values, where clientchain.pem is the client certificate chain, which contains both the private key and certificate concatenated into a single .pem file. To create this .pem file, you should copy the necessary certificates and private key (including the begin and end tags) into a single file. For example, a valid clientchain.pem would look similar to this:-----BEGIN CERTIFICATE----- MIIGsjCCBJqgAwIBAgICEAMwDQYJKoZIhvcNAQELBQAwOTELMAkGA1UEBhMCVVMx CzAJBgNVBAgMAkNBMQ0wCwYDVQQKDAROb25lMQ4wDAYDVQQDDAVTdWJDQTAeFw0x OTAxMDQwMzQwNDhaFw0yOTAxMDEwMzQwNDhaMDoxCzAJBgNVBAYTAlVTMQswCQYD ... frAVRAuCfJQJg6se/DSImzh55Era8uajoUtqrq/ueAlj9DpgZxOlZRISfRjVMf8R KFF8ijb/Ti6ZkQRCrZ1P4HAmAm7hMmsqVWNf0ZgGqd/85K7CDaw= -----END CERTIFICATE----- -----BEGIN RSA PRIVATE KEY----- MIIEpAIBAAKCAQEAysCIUiUR6ClYc61g2GHRvZTUiUZ6Lbc2Rp87w2qbULIxIRXA e/ETlNx47HrcmvWvGy9addTO4myuJOsUDANwc75GaXH9oA/3HeNf7H8zxk1qs1gx DO0b9njtrJWZni2rZnfcAHtf+2g7USWQ+MvH/vQFXeqOZbrFSu1Hxl9K4NErpfjt 07lt6rGfvWB5V5igUdtv7NtQihAclNwMKmVF/YrUpYO/FoLLdAnZlicU3H1zzDEP amkasUhaUOPIgnel1J7QQAm2wVSybdyPA4iGW/S89f54nGNdl7EOxQ== -----END RSA PRIVATE KEY----- -----BEGIN CERTIFICATE----- MIIFVTCCAz2gAwIBAgICEAAwDQYJKoZIhvcNAQELBQAwOjELMAkGA1UEBhMCVVMx CzAJBgNVBAgMAkNBMQ0wCwYDVQQKDAROb25lMQ8wDQYDVQQDDAZSb290Q0EwHhcN MTkwMTA0MDMyODQ0WhcNMjkwMTAxMDMyODQ0W -----END CERTIFICATE-----
- Check the access log to see what query is being performed so that you can replicate it, for example: [19/Jun/2019:11:23:07 +0800] SEARCH REQ conn=17 op=1 msgID=2 base="ou=certs,dc=am,dc=forgerock,dc=org" scope=sub filter="(CN=John Doe)" attrs="usercertificate,usercertificate;binary,cacertificate,cacertificate;binary"
- Perform a ldapsearch using the details from the access log and your connection details, for example:
- DS 7 and later: $ ./ ldapsearch --hostname ds.example.com --port 1389 --bindDN uid=admin --bindPassword password --baseDn "ou=certs,dc=am,dc=forgerock,dc=org" '(CN=John Doe)' dn cn uid userCertificate
- DS 6.x: $ ./ ldapsearch --hostname ds.example.com --port 1389 --bindDN "cn=Directory Manager" --bindPassword password --baseDn "ou=certs,dc=am,dc=forgerock,dc=org" '(CN=John Doe)' dn cn uid userCertificate
Example response:dn: uid=jdoe,ou=certs,dc=am,dc=forgerock,dc=org cn: John Doe uid: jdoe userCertificate;binary:: MIIG0zCCBLu....The response will confirm (or not) if the user can be found using your configuration, if they exist in your LDAP directory and if they have a valid certificate entry (userCertificate or userCertificate;binary attribute).
- Enable SSL debugging by adding the following to the setenv.sh file (typically located in the /tomcat/bin directory): export CATALINA_OPTS="-Djavax.net.debug=all"
- Set the java.security.debug option to certpath by adding the following to the setenv.sh file: export CATALINA_OPTS="-Djava.security.debug=certpath"
- If you are using OSCP validation, add ocsp to the java.security.debug option as well, for example: export CATALINA_OPTS="-Djava.security.debug=certpath,ocsp"
- Restart Tomcat.
The additional logging information will be output to the web application container log, for example, catalina.out for Tomcat.
|No value provided for attribute name to search CRL||The Issuer DN Attribute Used to Search LDAP for CRLs option has not been provided. See How do I configure certificate-based authentication in AM (All versions)? (Setting up CRL checking) for information on setting this option.|
|ERROR: X509Certificate: getRegCertificate is null||This error suggests that the certificate cannot be found in the LDAP directory. You should check if the user exists per Replicating searches in your LDAP directory.|
|AMCertStore.getCertificate: Certificate - get usercertificate is null||This error means the LDAP entry has been found but it does not contain a userCertificate or userCertificate;binary entry with the certificate in. You should check that the user has a valid userCertificate or userCertificate;binary entry per Replicating searches in your LDAP directory.|
|java.security.cert.CertPathValidatorException: Path does not chain with any of the trust anchors||This error usually indicates an issue with the certificate itself, for example, the certificate has failed the JVM's certificate checks. You should ensure your certificate is valid.|
Could not determine revocation status
Could not verify certificate
|The com.sun.security.enableCRLDP option has not been enabled in your web application container and/or the CA certificates that signed the user certificates are not trusted in the Java truststore. You should check the com.sun.security.enableCRLDP option has been set and the CA certificates are trusted.|
|CertPath:verify failed.||Indicates a failed CRL check. One possible reason for this, is AM does not trust the LDAP server certificate. See Prepare the truststore (AM 7 and later) or How do I make AM 6.x communicate with a secured LDAP server? for further information.|
|ERROR: AMCRLStore.getCRL: Error in getting CRL||
This error suggests the crlDistributionPoints field is not set or is incorrectly set in your user certificates.
The crlDistributionPoints field should look similar to this in your users' certificates:
CRLDistributionPoints [ [DistributionPoint: [URIName: http://ca.hostname.com/ca.crl, URIName: ldap:///CN=ds.example.com,CN=CDP,CN=Public%20Key%20Services,CN=Services,CN=Configuration,DC=org,DC=COM?certificateRevocationList?base?objectClass=cRLDistributionPoint] ]]
|Error getting Identity for user :User Requires Profile to Login|login_denied.jsp||This error means AM cannot locate the user profile in the data store. This may be an issue with the user not existing or a misconfiguration of the Access User Profile fields. See How do I configure certificate-based authentication in AM (All versions)? (Setting up LDAP checking) for information on setting these fields.|
|ERROR: AMCertPath.getResponderURLString: Invalid ocsp responder url configured java.net.MalformedURLException: no protocol:||This error means OSCP checking has been enabled, but the Responder URL and Certificate Nickname have not been set. See How do I configure certificate-based authentication in AM (All versions)? (Setting up OCSP validation) for information on setting these options.|