# OpenAM Administration Guide
2.2. Configuring Authentication Modules

Sidebar | Prev | Up | Next

### 2.2.4. Hints For the Certificate Authentication Module

X.509 digital certificates can enable secure authentication without the need for user names and passwords or other credentials. Certificate authentication can be handy to manage authentication by applications. If all certificates are signed by a recognized Certificate Authority (CA), then you might get away without additional configuration. If you need to look up public keys of OpenAM clients, this module can also look up public keys in an LDAP directory server.

When you store certificates and certificate revocation lists (CRL) in an LDAP directory service, you must configure both how to access the directory service and also how to look up the certificates and CRLs, based on the fields in the certificates that OpenAM clients present to authenticate.

Access to the LDAP server and how to search for users is similar to LDAP module configuration as in Section 2.2.12, “Hints For the LDAP Authentication Module”. The primary difference is that, unlike for LDAP configuration, OpenAM retrieves the user identifier from a field in the certificate that the client application presents, then uses that identifier to search for the LDAP directory entry that holds the certificate, which should match the certificate presented. For example, if the Subject field of a typical certificate has a DN `C=FR, O=Example Corp, CN=Barbara Jensen`, and Barbara Jensen's entry in the directory has `cn=Barbara Jensen`, then you can use `CN=Barbara Jensen` from the Subject DN to search for the entry with `cn=Barbara Jensen` in the directory.

ssoadm service name: `iPlanetAMAuthCertService`

Match Certificate in LDAP

  When enabled, OpenAM searches for a match for the user's certificate in the LDAP directory. If a match is found and not revoked according to a CRL or OCSP validation, then authentication succeeds.

  ssoadm attribute: `iplanet-am-auth-cert-check-cert-in-ldap`

Subject DN Attribute Used to Search LDAP for Certificates

  Indicates which attribute and value in the certificate Subject DN is used to find the LDAP entry holding the certificate.

  Default: CN

  ssoadm attribute: `iplanet-am-auth-cert-attr-check-ldap`

Match Certificate to CRL

  When enabled, OpenAM checks whether the certificate has been revoked according to a CRL in the LDAP directory.

  ssoadm attribute: `iplanet-am-auth-cert-check-crl`

Issuer DN Attribute Used to Search LDAP for CRLs

  Indicates which attribute and value in the certificate Issuer DN is used to find the CRL in the LDAP directory.

  Default: CN

  If only one attribute is specified, the LDAP search filter used to find the CRL based on the Subject DN of the CA certificate is `(`attr-name`=`attr-value-in-subject-DN`)`.

  For example, if the subject DN of the issuer certificate is `C=US, CN=Some CA, serialNumber=123456`, and the attribute specified is `CN`, then the LDAP search filter used to find the CRL is `(CN=Some CA)`.

  In order to distinguish among different CRLs for the same CA issuer, specify multiple attributes separated by commas (`,`) in the same order they occur in the subject DN. When multiple attribute names are provided in a comma-separated list, the LDAP search filter used is `(cn=`attr1`=`attr1-value-in-subject-DN`,`attr2`=`attr2-value-in-subject-DN`,...,`attrN`=`attrN-value-in-subject-DN`)`.

  For example, if the subject DN of the issuer certificate is `C=US, CN=Some CA, serialNumber=123456`, and the attributes specified are `CN,serialNumber`, then the LDAP search filter used to find the CRL is `(cn=CN=Some CA,serialNumber=123456)`.

  ssoadm attribute: `iplanet-am-auth-cert-attr-check-crl`

HTTP Parameters for CRL Update

  Your certificate authority should provide the URL to use here, from which OpenAM can get CRL updates.

  ssoadm attribute: `iplanet-am-auth-cert-param-get-crl`

Match CA Certificate to CRL

  When enabled, OpenAM checks the CRL against the CA certificate to ensure it has not been compromised.

  ssoadm attribute: `sunAMValidateCACert`

Cache CRLs in Memory

  When enabled, CRLs will be cached.

  ssoadm attribute: `openam-am-auth-cert-attr-cache-crl`

Update CA CRLs from CRLDistributionPoint

  When enabled, OpenAM updates CRLs from the LDAP directory store.

  ssoadm attribute: `openam-am-auth-cert-update-crl`

OCSP Validation

  Enable this to use Online Certificate Status Protocol (OCSP) instead of CRLs to check certificates' revocation status.

  If you enable this, you also must configure OSCP for OpenAM under Configuration > Server and Sites > Default Server Settings, or Configuration > Server and Sites > `Server Name` > Security.

  ssoadm attribute: `iplanet-am-auth-cert-check-ocsp`

LDAP Server Where Certificates are Stored

  Identifies the LDAP server with certificates. Remember to specify URLs with appropriate port numbers (389 for unencrypted LDAP, 636 for LDAP over SSL). When configuring a secure connection, scroll down to enable Use SSL/TLS for LDAP Access.

  ssoadm attribute: `iplanet-am-auth-cert-ldap-provider-url`

LDAP Search Start or Base DN

  Valid base DN for the LDAP search, such as `dc=example,dc=com`.

  ssoadm attribute: `iplanet-am-auth-cert-start-search-loc`

LDAP Server Authentication User, LDAP Server Authentication Password

  If OpenAM stores attributes in the LDAP directory, for example to manage account lockout, or if the LDAP directory requires that OpenAM authenticate in order to read users' attributes, then OpenAM needs the DN and password to authenticate to the LDAP directory.

  ssoadm attributes: `iplanet-am-auth-cert-principal-user`, and `iplanet-am-auth-cert-principal-passwd`

Use SSL/TLS for LDAP Access

  If you use SSL/TLS for LDAP access, OpenAM must be able to trust the LDAP server certificate.

  ssoadm attribute: `iplanet-am-auth-cert-use-ssl`

Certificate Field Used to Access User Profile

  If the user profile is in a different entry from the user certificate, then this can be different from subject DN attribute used to find the entry with the certificate. When you select other, provide an attribute name in the Other Certificate Field Used to Access User Profile text box.

  ssoadm attribute: `iplanet-am-auth-cert-user-profile-mapper`

Other Certificate Field Used to Access User Profile

  This field is only used if the Certificate Field Used to Access User Profile attribute is set to other. This field allows a custom certificate field to be used as the basis of the user search.

  ssoadm attribute: `iplanet-am-auth-cert-user-profile-mapper-other`

SubjectAltNameExt Value Type to Access User Profile

  Use this if you want to look up the user profile from an RFC 822 style name, or a User Principal Name as used in Active Directory.

  ssoadm attribute: `iplanet-am-auth-cert-user-profile-mapper-ext`

Trusted Remote Hosts

  Hosts trusted to send certificates to OpenAM, such as load balancers doing SSL termination, or OpenAM distributed authentication UI instances.

  ssoadm attribute: `iplanet-am-auth-cert-gw-cert-auth-enabled`

HTTP Header Name for Client Certificate

  If you configure trusted hosts, specify the HTTP header name for the client certificate inserted by the trusted host.

  ssoadm attribute: `sunAMHttpParamName`

Authentication Level

  Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

  ssoadm attribute: `iplanet-am-auth-cert-auth-level`