How To

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

Last updated Aug 27, 2019

The purpose of this article is to provide assistance on configuring certificate-based authentication in AM/OpenAM using the Certificate Authentication module.


2 readers recommend this article

Overview

Certificate-based authentication involves the use of standard X509 certificates for authenticating clients without using more traditional credentials such as usernames and passwords. This is achieved by checking a user's public-key certificate against ones held in an LDAP directory and/or validating the certificates using either certificate revocation lists (CRLs) in the LDAP directory or the Online Certificate Status Protocol (OCSP).

The Certificate Authentication Module utilizes the Java® API for certificate checking. The underlying web application container retrieves the certificate from the browser or smart card, and presents it to AM/OpenAM for checking during the authentication process.

Caution

It is assumed your users have the necessary certificates to interact with the Certificate Authentication module and you've imported the certificates and/or the CRLs into the LDAP directory. Generating user certificates, publishing them to your LDAP server, adding them to browsers or configuring smart cards is outside the scope of this article and ForgeRock support; if you want more tailored advice, consider engaging Deployment Support Services.

Options

There are 3 main options available to you when configuring the certificate authentication module:

  • LDAP checking - this option checks that the presented certificate matches one stored in the LDAP directory. It does not validate the certificate so you may want to consider combining this with one of the following validation options (CRL or OCSP). Access is denied if the certificate is not found or it doesn't match.
  • CRL checking - this option checks if the presented certificate has been revoked using a CRL. AM/OpenAM compares the certificate to the CRLs in the LDAP directory. Access is denied if the certificate is on a CRL. You can use this option with LDAP checking if required. 
  • OCSP validation - this option checks if the presented certificate has been revoked using the OCSP. AM/OpenAM uses the OCSP to validate the presented certificate. You can use this option with LDAP checking if required.

If you terminate SSL at a reverse proxy, refer to How do I configure AM/OpenAM (All versions) to check the HTTP header for the user certificate? for further information.

Authentication chains

When configuring authentication chains, you should only include the Certificate Authentication module in chains used by clients who will have certificates. This prevents users without certificates being prompted for their certificate. Therefore, if you have two groups of users; those required to present a certificate and those who are not, you should have two separate authentication chains.

Prerequisites

You should ensure the following are all set appropriately before configuring the Certificate Authentication module:

  • The com.sun.security.enableCRLDP option is enabled in your web application container if you are doing CRL checking. For example, if you are using Apache Tomcat™, you would add the following to the setenv.sh file (typically located in the /tomcat/bin/ directory):
    export CATALINA_OPTS="-Dcom.sun.security.enableCRLDP=true" 
  • The web application container in which AM/OpenAM is deployed handles user certificates correctly. For example, for Tomcat, you should set clientAuth to "want" in the server.xml file. 
  • Your certificates have the CRLDistributionPoint defined with valid URINames for http and ldap. For example, your certificates look similar to this:
    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]​
    ]]
  • Your system's truststore contains the root CA and any intermediate CAs that signed (issued) the client certificates. By default, Tomcat uses the Java truststore provided with the JDK that is located in $JAVA_HOME/jre/lib/security/cacerts
  • If you are using an LDAP directory for certificate checks and want to access it via SSL (recommended), AM/OpenAM must trust the LDAP server certificate. See How do I make AM/OpenAM (All versions) communicate with a secured LDAP server? for further information.  

Configuring the Certificate Authentication module

You can configure the Certificate Authentication module using either the console, Amster (AM 5 and later) or ssoadm:

Note

You must restart the web application container in which AM/OpenAM runs to apply these configuration changes.

Refer to the following sections for details on what options should be configured in each scenario: 

Setting up LDAP checking

Note

There is a known issue which prevents the Match Certificate in LDAP option working in AM 6.0.0.6, 6.5.0.1 and 6.5: OPENAM-14427 (Certificate Module with option "Match Certificate in LDAP" does not work). It is fixed in AM 6.0.0.7, 6.5.0.2 and 6.5.1.

If you want to check certificates in an LDAP directory, you must configure the following options in the Certificate Authentication module (described further in the documentation: Certificate Authentication Module Properties):

Option Description
Match Certificate in LDAP

Enable this setting to use LDAP checking. When enabled, AM/OpenAM searches for the user's certificate in the LDAP directory using the attribute specified in the following option as the filter. Once it has found a match, it compares the user's certificate with the one in the LDAP directory:

  • Access is allowed if a match is found and no other validation is required.
  • Access is denied if the certificate is not found or doesn't match.
Subject DN Attribute Used to Search LDAP for Certificates Specify the attribute to use for searching the LDAP directory. For example, if you specify CN as the attribute, AM/OpenAM retrieves the CN value (for example, CN=John Doe) from the certificate and searches the LDAP directory using that as the search filter.
Match Certificate to CRL

Optional. Enable only if you want CRL checking in addition to LDAP checking. 

See the Setting up CRL checking section for more information on the other settings needed to configure these checks.

OCSP Validation Optional. Enable only if you want OCSP validation in addition to LDAP checking. 

See the Setting up OCSP validation section for more information on the other settings needed to configure this validation.

LDAP Server Where Certificates are Stored

LDAP Search Start or Base DN

LDAP Server Authentication User

LDAP Server Authentication Password

Use SSL/TLS for LDAP Access

Specify these details for the LDAP server you are using for certificate-based authentication. 
Certificate Field Used to Access User Profile

Specify the attribute in the certificate that represents the username. This is used to look up the user in AM/OpenAM. The following are valid entries:

  • subject DN
  • subject CN
  • subject UID
  • email address
  • other
  • none

 If you want to specify a different attribute, use 'other' and then specify the actual attribute in the following option. 

Other Certificate Field Used to Access User Profile Specify the attribute in the certificate that represents the username. You should only populate this option if you specified 'other' in the above option.
SubjectAltNameExt Value Type to Access User Profile Used in conjunction with the above two options; set to 'none' to give preference to above options. See documentation for alternatives.

LDAP directory

You must ensure the following:

  • All users who should authenticate using certificates exist in the LDAP directory.
  • They can be found using the attribute you specified in the Subject DN Attribute Used to Search LDAP for Certificates option.
  • They have a userCertificate or userCertificate;binary entry that contains their certificate.
  • The CA certificates that signed the user certificates are trusted in the Java truststore.
  • You can connect to the LDAP directory from AM/OpenAM.

Setting up CRL checking

If you want to check certificates against the CRLs found in the LDAP directory, you must configure the following options in the Certificate Authentication module (described further in the documentation: Certificate Authentication Module Properties):

Option Description
Match Certificate to CRL

Enable this setting to use CRL checking. When enabled, AM/OpenAM compares the certificate against the CRLs found in the LDAP directory:

  • Access is allowed if the certificate is not on a CRL.
  • Access is denied if the certificate is on a CRL (revoked).

CRLs are searched for using the attribute specified in the following option. 

Issuer DN Attribute Used to Search LDAP for CRLs Specify the attribute to use for searching the LDAP directory for the CRLs. This is the attribute name of the certificate's issuer subjectDN value found in the CA certificate.
HTTP Parameters for CRL Update

Specify the parameters that should be included in any HTTP CRL calls made to the CA who issued the certificate. If the Client or CA certificate contains the IssuingDistributionPointExtension or the CRLDistributionPointsExtension, AM/OpenAM uses this information to update the CRL by retrieving it from the distribution point.

These parameters should be specified as key pairs separated by commas, for example: param1=value1,param2=value2.

Contact your CA administrator for these parameters.

Match CA Certificate to CRL

Enable this option to check the CRL against the CA certificate to ensure it has not been compromised.

This option must also be enabled if you want AM/OpenAM to update CRLs in the LDAP directory.

Cache CRLs in memory Enable this setting to cache the CRLs. When enabled, AM/OpenAM reads a CRL and holds it in the cache until AM/OpenAM is restarted or until it is updated in the LDAP directory. It can only be updated in the LDAP directory if the following option is enabled.
Update CA CRLs from CRLDistributionPoint

Enable this setting to allow AM/OpenAM to update CRLs in the LDAP directory. When enabled, AM/OpenAM checks the nextUpdate date field in the CRL each time it uses it. Once this date has passed, AM/OpenAM fetches new CA CRLs from the CRLDistributionPoint and updates the CRL held in the LDAP directory.

This option is only used if the Match CA Certificate to CRL option is enabled.

LDAP Server Where Certificates are Stored

LDAP Search Start or Base DN

LDAP Server Authentication User

LDAP Server Authentication Password

Use SSL/TLS for LDAP Access

Specify these details for the LDAP server you are using for certificate-based authentication. 

LDAP directory

You must ensure the following:

  • The CRLs exist in the LDAP directory.
  • They can be found using the attribute you specified in the Issuer DN Attribute Used to Search LDAP for CRLs option.
  • You can connect to the LDAP directory from AM/OpenAM.

Web application container

Ensure you have set the com.sun.security.enableCRLDP option to true in your web application container as detailed in the Prerequisites section.

Setting up OCSP validation

If you want to do OCSP validation, you must configure the following options in the Certificate Authentication module (described further in the documentation: Certificate Authentication Module Properties):

Option Description
OCSP Validation

Enable this setting to use the OCSP to validate the certificate. When enabled, AM/OpenAM issues a real time status request to check the validity of the certificate. Certificates tend to contain the URL of the OCSP server for this purpose. A response is then returned to the Responder URL:

  • Access is allowed if a successful response is received.
  • Access is denied if an unsuccessful response is received.
Certificate Field Used to Access User Profile

Specify the attribute in the certificate that represents the username. This is used to look up the user in AM/OpenAM. The following are valid entries:

  • subject DN
  • subject CN
  • subject UID
  • email address
  • other
  • none

 If you want to specify a different attribute, use 'other' and then specify the actual attribute in the following option. 

Other Certificate Field Used to Access User Profile Specify the attribute in the certificate that represents the username. You should only populate this option if you specified 'other' in the above option.
SubjectAltNameExt Value Type to Access User Profile Used in conjunction with the above two options; set to 'none' to give preference to above options. See documentation for alternatives.

Once you have enabled OCSP validation, you must configure the Responder URL and Certificate Nickname using either the console, Amster (AM 5 and later) or ssoadm: 

  • AM / OpenAM 13.5 console: navigate to: Configure > Server Defaults > Security > Online Certificate Status Protocol Check, and complete the Responder URL and Certificate Nickname fields.
  • Pre-OpenAM 13.5 console: navigate to: Configuration > Servers and Sites > Default Server Settings > Security, and complete the Responder URL and Certificate Nickname fields.
  • Amster: follow the steps in How do I update property values in AM (All versions) using Amster? with these values:
    • Entity: SecurityProperties
    • Property: com.sun.identity.authentication.ocsp.responder.url and com.sun.identity.authentication.ocsp.responder.nickname
  • ssoadm: enter the following command:
    $ ./ssoadm update-server-cfg -s default -u [adminID] -f [passwordfile] -a com.sun.identity.authentication.ocsp.responder.url=[url] com.sun.identity.authentication.ocsp.responder.nickname=[nickname]
    replacing [adminID, [passwordfile], [url] and [nickname] with appropriate values.

See Reference › Online Certificate Status Protocol Check for further information.

See Also

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

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

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

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...