Integration with Smart Cards

The PAM WEB Server provides a mechanism to authenticate users who present client certificates (X.509) during the login process.

The client certificate might come from a Smart Card or be deployed into a user’s browser.

The document below describes the PAM configuration to enable client certificate authentication.

Note: this document describes configuration on Linux. For Windows, all is almost the same except paths to files and executable names.

  1. Create new trust store with root CA certificate in it:
    • Go to PAM folder and run followed command:

    Copy 
    bin/PamKeytool.sh -import -file /path/to/ad2_root.cer -alias trustedCA -keystore /opt/xtam/web/conf/truststore.jks

    • Enter a new password for the newly created cert store.
    • Answer yes, once it asks for trust cert or not.
    • Example output is in the following screenshot:

    Smart_Cards1

  2. Stop pammanager / PamManagement service (depends on host OS).
  3. Edit $PAM_HOME/web/conf/server.xml.
    • Add the following properties to connector configuration below

      • "BEGIN: SELF SIGNED SSL" comment: truststoreFile="/opt/xtam/web/conf/truststore.jks" truststorePass="pass@word1",

      where truststoreFile is the path to trust certificate store from step 1 and truststorePass is password for this store.

    • Change clientAuth property value from "false" to "want" - if you want to have a fall back to certificate/smartcard authentication with forms based auth, or to "true" - if you want to force PAM to use certificate/smartcard authentication only.
    • You can see the configuration example in the screenshot below:

    Smart_Cards2.png

  4. Edit $PAM_HOME/web/conf/catalina.properties.

    Add this property like on screenshot below:

    cas.authn.x509.principalType=SUBJECT_ALT_NAME

    Smart_Cards3.png

    By default, this parameter is sufficient to work with certificates, but only in the case of one internal certificate authority, if there are subordinate CAs, and the user certificate is issued, you need to add the second parameter:

    cas.authn.x509.max-path-length-allow-unspecified=true

  5. Move cas.war and cas folder from $PAM_HOME/web/webapps/ to some location outside $PAM_HOME folder for being able to revert those changes.

  6. Download x509-enabled CAS module.

  7. Put downloaded cas.war file to $PAM_HOME/web/webapps/ folder. Changing the ownership of this file may be necessary.

    For example, if PAM services are running under xtam user account and PAM is deployed to /opt/xtam/, followed command will change ownership for all files inside this directory: chown -R xtam:xtam /opt/xtam.

    Start pammanager / PamManagement service (depends on host OS).

  8. After services start certificate/smartcard authentication should work.

    Additional configuration on client PC might be needed, for example installing smartcard drivers or put certificate to OS/browser trusted certificate store.