How To

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

Last updated Aug 23, 2019

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


1 reader recommends this article

Troubleshooting

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 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/OpenAM (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 How do I enable Message level debugging in AM/OpenAM (All versions) 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/OpenAM (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/OpenDJ (All versions)? for further information if you are using DS/OpenDJ.
  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.
Note

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, com.sun.security.enableCRLDP has been set to true.
Got client cert =
[
[
  <certificate detail>

]
Indicates AM/OpenAM has successfully retrieved the certificate.
Cert.doRevocationValidation: crls size = 0
Indicates AM/OpenAM is performing the CRL checks.
CertPath:verify success.
Indicates a successful CRL check.

Authenticating with your certificate using curl

You can use one of the following curl commands to check that you can authenticate using your certificate; the -v option is included for a verbose output to aid troubleshooting: 

  • AM 5 and later:
    $ curl -v -X POST -H "Accept-API-Version: resource=2.1" "https://www.host1.example.com:8443/openam/json/realms/root/authenticate?authIndexType=module&authIndexValue=[moduleName]" --cert [clientchain.pem]
    
  • Pre-AM 5:
    $ curl -v -X POST "https://www.host1.example.com:8443/openam/json/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-----

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 an ldapsearch using the details from the access log and your connection details, for example:
    $ ./ ldapsearch --hostname ds1.example.com --port 1389 --bindDN "cn=Directory Manager" --bindPassword password --baseDn "ou=certs,dc=openam,dc=forgerock,dc=org" '(CN=John Doe)'  dn cn uid userCertificate
    
    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 setenv.sh file (typically located in the /tomcat/bin directory):
    export CATALINA_OPTS="-Djavax.net.debug=all"
  2. Set the java.security.debug option to certpath by adding the following to the setenv.sh file:
    export CATALINA_OPTS="-Djava.security.debug=certpath"
  3. 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"
  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/OpenAM (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 checks 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/OpenAM does not trust the LDAP server certificate. See How do I make AM/OpenAM (All versions) 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=ds1.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/OpenAM 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/OpenAM (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/OpenAM (All versions)? (Setting up OCSP validation) for information on setting these options.

See Also

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

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

How do I import a certificate into the truststore used by AM/OpenAM (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

N/A

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 © 2019 ForgeRock, all rights reserved.
Loading...