Authenticating with the Common Access Card (CAC)

The Common Access Card is the standard identification for active duty uniformed service personnel, Selected Reserve, DoD civilian employees, and eligible contractor personnel in the United States. It is used to enable physical access to buildings and controlled spaces, and provides access to DoD computer networks and systems. The CAC can be used for access into computers and networks that are equipped with various smart card readers. When it is inserted into the reader, the device asks the user for a PIN. This task helps you set up AppScan® Enterprise to allow CAC authentication over LDAP so that users can log in to AppScan® Enterprise without providing a user name and password.

Before you begin

During installation and configuration, make sure that you select LDAP authentication in the Authentication Mechanism screen of the configuration wizard.
Note:
  1. If CAC was enabled before you apply AppScan Enterprise v9.0.3.1 iFix1, disable it before you run the configuration wizard during the iFix1 installation. Then, you can re-enable CAC and log in to AppScan Enterprise and complete the following task.
  2. No user actions are required to enable authentication by using Microsoft™ Edge. For Mozilla Firefox users, your organization might have specific instructions for enabling CAC in the browser.

Procedure

  1. Install AppScan® Enterprise by using an LDAP server that contains the CAC users.
  2. Make sure that the Product Administrator for AppScan Enterprise is also a CAC user.
    1. Log in to AppScan Enterprise as an administrator.
    2. Go to Administration > Users and Groups, and select Default User from the list.
    3. On the Edit User page, select Administrator from the Type list. Finish configuring the user properties, click Save, and then log out of AppScan Enterprise.
  3. Import the full certificate authority chain into the truststore.
    1. Create a keystore file or use your existing keystore.
      Note: To generate a keystore, you can use keytool. AppScan Enterprise includes a keytool, and can be downloaded from <install-dir>\AppScan Enterprise\Liberty\jre\bin\

      Use this command:
      keytool -genkey -alias mydomain.com -keyalg RSA -keystore MyKeystore.jks
      -keysize 2048 - keypass storePassword

    2. Import the full CA certificate chain that signed the client certificates that exist on the CAC cards.
      Note: You can use a Java™ iKeyman tool to manage your digital certificates. With iKeyman, you can add certificate authority (CA) roots to your database, copy certificates form one database to another, request and receive a digital certificate from a CA, set default keys, and change passwords. The iKeyman utility is included with AppScan® Enterprise and is stored in <install-dir>\AppScan Enterprise\Liberty\jre\bin\ikeyman.exe. You can download additional information on iKeyman from IBM DeveloperWorks: iKeyman Guide.
    3. Add the CA certificates, one at a time, and create a label for each one. If you use iKeyman, you can also create a label for each one. After you finish adding all the certificates of the full chain, close the iKeyman tool.
    4. If defaultTrustStore that is available at location: 
      <install-dir>\AppScan Enterprise\Liberty\usr\servers\<ase instance name>\resources\security\cacerts
      is used as trustStore, then re-running the configuration wizard will require certificate chain to be reimported. If this must be avoided, then before running the configuration wizard import the certificate chain into the trustStore file, available at location:
      <install-dir>\AppScan Enterprise\Liberty\templates\servers\defaultServer\resources\security\cacerts
  4. Modify the web.xml file to replace Form-Based Authentication with Client-Certificate Authentication.
    Note: Make a backup of the web.xml file before you modify it.
    1. Stop the HCL AppScan Enterprise Server service.
    2. Locate the AppScanServerWeb.war file of your AppScan® Enterprise instance that is in: <install-dir>\AppScan Enterprise\Liberty\usr\servers\ase\apps\AppScanServerWeb.war.
    3. Rename the AppScanServerWeb.war file to AppScanServerWeb.zip and navigate into the WEB-INF folder to retrieve the web.xml file for editing.
    4. Replace the following section of the file:

      <login-config>
      <auth-method>FORM</auth-method>
      <form-login-config>
      <form-login-page>/pages/Login.jsp</form-login-page>
      <form-error-page>/pages/Login.jsp?Retry=True</form-error-page>
      </form-login-config>
      </login-config>

      with

      <login-config>
      <auth-method>CLIENT-CERT</auth-method>
      </login-config>

    5. Save the file and rename AppScanServerWeb.zip to AppScanServerWeb.war.
  5. Modify the server.xml file to enforce SSL protocol, set the trust keystore and set the LDAP certificate mapping.
    1. Locate the server.xml file at <install-dir>\AppScan Enterprise\Liberty\usr\servers\<ase instance name>\server.xml.
    2. Make sure that the <featureManager> section contains <feature>ssl-1.0</feature>.
    3. Locate the <keystore> section of the file and add this line: <keyStore id="cacTrustKeyStoreID" password="store password" location="cacTrustKeyStore.jks" type='jks' />, where
      • id is a string that uniquely identifies the keystore (use any string)
      • password is the password of the keystore (this value can be stored in clear text or encoded form; use the securityUtility from Liberty to encode the password)
      • location is an absolute or relative path to the keystore file (the relative path points to <install-dir>\AppScan Enterprise\Liberty\usr\servers\<ase instance name>\resources\security\
      • type is the type of the keystore. jks is the default value.
      Note: See Liberty profile: Keystores.
    4. Locate the <ssl> section of the file, and make sure that it includes <ssl-Protocol="SSL_TLSv2">.
    5. Add these attributes to <ssl>
      • trustStoreRef="cacTrustKeyStoreID" where cacTrustKeyStoreID is the ID of the keystore that was configured in the <keystore> section of the file.
      • clientAuthenticationSupported="true"
      The section might look like this example when you're done editing: <ssl id="defaultSSLConfig" sslProtocol="SSL_TLSv2" keyStoreRef="defaultKeyStore" trustStoreRef="defaultKeyStore" clientAuthenticationSupported="true" />.
    6. Locate the <ldapRegistry> section of the file and add these attributes:
      • certificateMapMode="CERTIFICATE_FILTER"

      • certificateFilter="<ldapAttribute>=${<certificateAttribute>} (replace <ldapAttribute> and <certificateAttribute> accordingly)

        Note: The values for ldapAttribute and certificateAttribute depends on the type of the LDAP server and the attributes of the certificate. Modify the example of this filter according to your environment.
      One such certificateFilter can be:

      certificateFilter="uid=${SubjectCN}"

      The "uid" attribute in the LDAP record must match the SubjectCN attribute of the certificate. If the "SubjectCN" of the certificate is "admin", then the user name (uid) in the LDAP directory must be "admin".

      The following example shows an LDAP registry configuration that uses IBM® Tivoli® Directory Server. The uid attribute from the LDAP server match the SubjectCN attribute in the certificates stored on the CAC card:

      <ldapRegistry ldapType="IBM Tivoli Directory Server" host="<<hostname>>" port="<<Port no>>" sslEnabled="false" baseDN="o=IBM,c=US "certificateMapMode="CERTIFICATE_FILTER" certificateFilter="uid=${SubjectCN}"> <activedFilters userFilter="(objectclass=Person)" userIdMap="*:uid"/> </ldapRegistry>
  6. Restart the HCL AppScan Enterprise Server service.
  7. Log back in to AppScan Enterprise as an administrator with your CAC authentication.
  8. Go to Administration > Users and Groups, and change the permissions for the default user back to whatever permissions you want that role to have. (Typically, you would not want the default user to be an administrator, but perhaps a Standard User instead).
  9. After AppScan Enterprise is configured, there is no other way to create the Administrator account for the CAC user, except by using a database query. If you did not complete Step 2, follow these steps:
    1. Log in to AppScan Enterprise with your CAC card, and check your permissions to see if you are an Administrator.
    2. If you are not an administrator, run this query against your AppScan Enterprise SQL Server database: select *from UserInfo.
    3. Locate the CAC user in the query results and note their UserId.
    4. Then, run this query: Update UserInfo set UserTypeId=5, LicenseType=3, EffectiveType=32768, where UserId is the ID of your CAC admin user.
    5. Log out of AppScan Enterprise, and then log in again. You should now be an administrator.

Results

Users that use Common Access Cards are able to log in to AppScan® Enterprise without providing a user name and password.