Chapter
9
Using CAC for authentication
The following topics are provided: ! CAC configuration overview (page 72) ! Modifying the Tomcat server (page 72) ! Importing DoD CA certificates (page 73) ! Validating CAC certificates (page 74) ! Specifying CAC users (page 76) ! Enabling CAC Chain (page 78)
CAC configuration overview
The Common Access Cards (CAC) support within BMC Atrium SSO leverages the Certificate module of OpenSSO. To simplify the user experience, many of the required steps to use the Certificate module have already been performed.
To use CAC for authentication
1 “Modifying the Tomcat server”
2 “Importing DoD CA certificates”
3 “Validating CAC certificates” 4 “Specifying CAC users”
5 “Enabling CAC Chain”
Beyond the scope of this document is acquiring CAC cards, the DoD CA
certificates, and the installation and configuration of card readers and middleware software for these card readers. The administrator who is configuring BMC Atrium SSO for CAC authentication is assumed to be familiar with these topics. BMC Atrium SSO supports using CAC cards through the ActivClient software from ActivIdentity. See the ActivClient documentation for the configuration steps needed for clients to use CAC cards, card readers, and browser setup.
Modifying the Tomcat server
Before selecting the CAC Chain to use for authentication, the Tomcat server hosting the BMC Atrium SSO application must be configured to ask clients for certificates and the Tomcat server’s truststore must be set up with the root certificates for the CAC cards and the OCSP server.
To modify the Tomcat server for CAC Chain authentication
1 Stop the BMC Atrium SSO Tomcat server.
2 Edit the following file:
installationDirectory/BMC Software/BMC Atrium SSO/tomcat/conf/ server.xml
3 Search the file to find the Connector definition used to configure the server's HTTP and HTTPS communications. The tag is similar to the following:
Chapter 9 Using CAC for authentication 73 Importing DoD CA certificates
truststorePass="changeit" />
4 Change the clientAuth attribute from “false” to “want” clientAuth="want".
The clientAuth attribute enables Tomcat to ask for client certificates.
IMPORTANT
Do not set the clientAuth attribute to “true” because this setting breaks certain BMC Atrium SSO-to-Agent communications.
After the change, the Connector tag is similar to the following:
<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" maxThreads="150" scheme="https" secure="true" clientAuth="want" sslProtocol="TLS"
keystoreFile="C:\Program Files\BMC Software\BMC Atrium SSO\tomcat/conf/keystore.p12"
keystorePass="internal4bmc"
truststoreFile="C:\Program Files\BMC Software\BMC Atrium SSO\tomcat/conf/cacerts.p12"
truststorePass="changeit" />
Importing DoD CA certificates
The DoD CA certificates appropriate for your CAC cards must be imported into the BMC Atrium SSO server's truststore before using CAC for authentication. Importing the certificates allows the server to send the appropriate query to the client to return the correct certificate. Refer to the documentation from the supplier of your CAC cards for the location where the current root certificates can be acquired.
The server's truststore (named cacerts.p12) is located in the
installationDirectory/BMC Software/BMC Atrium SSO/tomcat/conf. The following instructions uses the Oracle keytool utility to import the certificate, but another tool could also be used.
To import certificates
1 Add the bin directory to the PATH environment variable.
When BMC Atrium SSO is installed with its own Tomcat server, a JDK is installed with the server. When using this JDK, the DoD certificate can be imported into the server's truststore by using the keytool command (keytool.exe on Windows), located within the JDK's bin directory. This bin directory needs to be added to the PATH environment variable if it is not already a part of that variable.
2 To add the location, run the following commands:
UNIX:
export PATH=<installationLocation>/BMC Software/BMC Atrium SSO/ jdk/bin:$PATH
Windows:
set PATH=<installationLocation>\BMC Software\BMC Atrium SSO\jdk\bin;%PATH%
3 Use the keytool utility to copy the DoD CA certificate file into the following directory:
installationDirectory/BMC Software/BMC Atrium SSO/tomcat/conf
4 Use the keytool utility to import the certificate into the truststore using the following parameters:
keytool -importcert -keystore cacerts -file DOD_CA19.car -alias DOD_CA19 -storetype PKCS12 -providername JsafeJCE
NOTE
In this example, the certificate file name, DOD_CA19.cer, may not be appropriate for your use.
5 Enter the password (the default is changeit).
6 Accept the certificate at the prompt.
7 If SSL is used to communicate with an external LDAP server, import that server’s certificate into the truststore.
! Use the keytool utility to import the LDAP server’s certificate into the BMC Atrium SSO truststore.
! If the LDAP server requires a client certificate, export the BMC Atrium SSO certificate and import it into the LDAP server’s truststore before enabling CAC Chain.
! If CA signed certificates are used for LDAPs, import the CA signed certificate and any intermediate signing certificates into the truststores instead.
8 Restart the Tomcat server.
Validating CAC certificates
CAC certificates can be validated by configuring BMC Atrium SSO to use either OCSP responder certificates or a Certificate Revocation Lists (CRL). BMC does not recommended using the CRL approach due to the performance load experienced with the ever-increasing length of CRL lists. These lists can grow to be very large which affects the network and server when retrieving the data.
Chapter 9 Using CAC for authentication 75 Validating CAC certificates
To configure BMC Atrium SSOto use OCSP responder
1 Navigate to the Servers and Sites tab: Configuration > Servers and Sites
2 Click the server link.
3 Click the Security tab.
4 Click the Online Certificate Status Protocol Check link
5 Verify that alias for this certificate is DoDocspCertificate, otherwise the nickname specified for the server configuration must be updated to the correct value. The alias (nickname) is used to store the OCSP responder certificate in the truststore.
6 Verify that the Responder URL field is correct for the installation site. If not, update the URL.
NOTE
If a responder URL is not specified, the value within the certificate is used.
Using CRL to validate certificates
Instead of relying upon OCSP (the recommended approach for validating CAC certificates), BMC Atrium SSO can be configured to use a Certificate Revocation List (CRL).
To configure BMC Atrium SSOto use CRL
1 Navigate to the Authentication tab:
Access Control > BmcRealm link > Authentication tab
2 Click Module Instances.
3 Click CAC.
4 In the OCSP Validation field, deselect Enabled (if selected).
5 In the Issuer DN Attribute Used to Search LDAP for CRLs field, enter the DN.
6 In the HTTP Parameters for CRL Update field, enter the parameters.
7 In the Match CA Certificate to CRL field, click Enabled.
8 Click Save.
Contact the CA signed certificate administrator for the following parameters and values:
! Issuer DN Attribute Used to Search LDAP for CRLs value. This value is used to access the server where the CRL is stored.
! HTTP Parameters for CRL Update parameters. These parameters are used to contact the servlet for the CRL.
Specifying CAC users
BMC Atrium SSO can be configured to allow any valid CAC card access or it can be configured to allow a known subset authentication. This section describes the following methods for specifying CAC user:
! Allowing any user access with a valid CAC card
! Allowing a subset of users access through the internal data store ! Allowing a subset of user access through an external LDAP server
Allowing any user access with a valid CAC card
To allow any user with a valid CAC card access
1 Navigate to the Authentication tab:
Access Control > BmcRealm link > Authentication tab
2 Click All Core Settings.
3 Click DynamicorIgnore. 4 Click Save.
Allowing a subset of users access through the internal data store
The set of known users that are allowed access can be specified by using the internal data store.
To allow access by using the internal data store
1 Verify that the User Profile is set as Required.
2 Create the users that need access in the internal data store.
To set the User Profile
1 Navigate to the Authentication tab:
Access Control > BmcRealm link > Authentication tab
2 Click All Core Settings.
Chapter 9 Using CAC for authentication 77 Specifying CAC users 3 Enter the new user ID.
The ID of the new user must match the Common Name (CN) of the owner of the CAC card.
4 Enter the user information.
5 Enter the default password into the Password and Password (confirm) fields. The password field must be specified, although with CAC authentication, it is ignored.
6 In the User Status field, verify that Active is selected (default).
7 Click OK.
Allowing a subset of user access through an external LDAP server
The set of known users that are allowed access can be specified by using an external LDAP server where the users certificates are stored.
To configure BMC Atrium SSO to use an external LDAP server, follow the directions in this section.
To configure BMC Atrium SSO to use an external LDAP server
1 Navigate to the Authentication tab:
Access Control > BmcRealm link > Authentication tab
2 Click Module Instances.
3 Click CAC.
4 In the Match Certificate in LDAP field, click Enabled.
5 In the Subject DN Attribute Used to Search LDAP for Certificates field, enter the attribute from the Subject DN of the certificate that is used to search the LDAP server for certificates.
The default value is CN.
6 In the LDAP Server Where Certificates are Stored field, enter the LDAP server information.
The host name must end with a colon (:) followed by the port number for the LDAP server.
7 In the LDAP Search Start DN field, enter the DN of the node. The DN of the node starts the search within the LDAP server.
To connect with the LDAP server, the user must have sufficient privileges to perform the search.
8 In the LDAP Server Principal User field, enter the DN of the user with search privileges in the LDAP server.
9 In the LDAP Server Principal Password field, enter the password for this user and repeat this password in the LDAP Server Principal Password (confirm) field to confirm the first entry.
10 If you plan to use SSL for communication with the LDAP server, in the Use SSL for LDAP Access field, click Enabled.
If you are using SSL, the LDAP server certificate must be imported into the BMC Atrium SSO truststore so that SSL can connect with the LDAP server.
11 Click Save.
Enabling CAC Chain
After the BMC Atrium SSO and the CAC module have been configured, CAC Chain must be selected for user authentication. Log on to the administrator console by using the administrator account and the password specified during the installation of BMC Atrium SSO.
To select the CAC Chain
1 Navigate to the Authentication tab:
Access Control > BmcRealm link > Authentication tab
2 Click All Core Settings.
A new page is displayed. At the top of this new page is a series of radio buttons. These buttons are used to select how the user profile is handled when a user is authenticated.
3 If using the internal data store for user selection, in the User Profile field, click either Dynamic or Ignored.
If you are not using the internal data store for user selection, in the User Profile
field, click Dynamic.
! Dynamic specifies that a local SSO user profile is created after a successful authentication, if the user profile does not already exist.
! Ignored specifies that no local SSO user profile is created or required for authentication.
4 Click Save.
5 Click Back to Authentication.
6 On the Authentication page, select CAC Chain from the Administration Authentication Configuration drop down menu.
Chapter 9 Using CAC for authentication 79 Troubleshooting CAC authentication
URL certificate authentication not enabled
If the BMC Atrium SSO \WEB-INF\config\Atrium
SSO\debug\Authentication directory contains the following error messages, then the CAC certificate was not passed in from the client.
Ensure that the certificates, or the correct certificates, were imported into the cacerts file.
amAuthCert:11/18/2009 01:17:37:922 PM CST: Thread[http-8443- 6,5,main]
ERROR: Certificate: cert passed in URL not enabled for this client amAuthCert:11/18/2009 01:17:37:922 PM CST: Thread[http-8443-
6,5,main]
ERROR: Certificate: exiting validate with exception
com.sun.identity.authentication.spi.AuthLoginException: URL certificate authentication not enabled.
at com.sun.identity.authentication.modules.cert.Cert.process(Cert.jav a:383) at com.sun.identity.authentication.spi.AMLoginModule.wrapProcess(AMLo ginModule.java:866) at com.sun.identity.authentication.spi.AMLoginModule.login(AMLoginMod ule.java:926) at sun.reflect.GeneratedMethodAccessor57.invoke(Unknown Source) ....
OCSP verify failed
If you receive the following errors, verify that you imported the OCSP certificates into the cacerts.p12 file:
amAuthCert:11/18/2009 02:45:58:004 PM CST: Thread[http-8443- 3,5,main]
ERROR: CertPath:verify failed.
amAuthCert:11/18/2009 02:45:58:004 PM CST: Thread[http-8443- 3,5,main]