How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I troubleshoot certificate-based authentication issues in AM (All versions)?

Last updated Apr 13, 2021

The purpose of this article is to help you troubleshoot certificate-based authentication issues in AM when you are using the Certificate Authentication module.

2 readers recommend this article


If you are experiencing issues with the Certificate Authentication module, you can try these troubleshooting steps to find and resolve the issue: 

  1. Check that you have met all the prerequisites; in particular ensure the 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.
  2. Check that you can successfully authenticate with your certificate using curl to help isolate if the certificate is causing an issue.
  3. 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.
  4. Collect logs and check the Common errors section for further information about errors you find along with possible solutions:
    1. Collect message level debug logs as detailed in Maintenance Guide › Debug Logging (AM 7 and later) or How do I enable Message level debugging in AM 5.x and 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)?
    2. 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™).
    3. 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.
  5. 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. 

Confirmation messages

The following table provides some common messages you will see in the logs to indicate progress and help you work out where the process is failing:

Message Meaning
AMCertPath.verify: crlEnabled ---> true Indicates the JAVA API is configured for CRL checking, that is, 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.

Authenticating with your certificate using curl

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" "[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:


Replicating searches in your LDAP directory

You can check that you can find a user in your LDAP directory using the details you specified when configuring the module:

  1. 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=openam,dc=forgerock,dc=org" scope=sub filter="(CN=John Doe)" attrs="usercertificate,usercertificate;binary,cacertificate,cacertificate;binary"
  2. Perform a ldapsearch using the details from the access log and your connection details, for example:
    • DS 7 and later:  $ ./ ldapsearch --hostname --port 1389 --bindDN uid=admin --bindPassword password --baseDn "ou=certs,dc=openam,dc=forgerock,dc=org" '(CN=John Doe)' dn cn uid userCertificate
    • Pre-DS 7: $ ./ ldapsearch --hostname --port 1389 --bindDN "cn=Directory Manager" --bindPassword password --baseDn "ou=certs,dc=openam,dc=forgerock,dc=org" '(CN=John Doe)' dn cn uid userCertificate

Example response:dn: uid=jdoe,ou=certs,dc=openam,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).

Enabling debug options in your container

There are a few certificate related debug options you can enable in your web application container to help identify failures. The following options assume you are using Tomcat:

  1. Enable SSL debugging by adding the following to the file (typically located in the /tomcat/bin directory): export CATALINA_OPTS=""
  2. Set the option to certpath by adding the following to the file: export CATALINA_OPTS=""
  3. If you are using OSCP validation, add ocsp to the option as well, for example: export CATALINA_OPTS=",ocsp"
  4. Restart Tomcat.

The additional logging information will be output to the web application container log, for example, catalina.out for Tomcat.

Common errors

The following table provides some common errors you might see in the logs and possible solutions:

Error Solution
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. 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 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 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 Installation Guide › Preparing a Truststore (AM 7 and later) or How do I make AM 5.x and 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:, URIName: ldap:///,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 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.

See Also

How do I configure certificate-based authentication in AM (All versions)?

How do I configure AM (All versions) to check the HTTP header for the user certificate?

How do I import a certificate into the truststore used by AM (All versions) for SSL?

Authentication and Single Sign-On Guide › Certificate Authentication Module

Authentication and Single Sign-On Guide › Certificate Authentication Module Properties

Java PKI Programmer's Guide > CertPath Implementation in SUN Provider

RFC 6960: Online Certificate Status Protocol - OCSP

Related Training


Related Issue Tracker IDs

OPENAM-15084 (Certificate Auth module docs for CRL Cache - LDAP only)

OPENAM-15083 (Certificate Auth module needs detailed documentation)

OPENAM-14427 (Certificate Module with option "Match Certificate in LDAP" does not work)

OPENAM-13819 (RFE: creation of three new Auth Tree Nodes)

Copyright and TrademarksCopyright © 2021 ForgeRock, all rights reserved.