Using CAC for authentication

BMC Atrium Single Sign-On supports Common Access Card (CAC) authentication. Beyond the scope of this document is acquiring CACs, the Department of Defense (DoD) Certificate Authority (CA) certificates, and the installation and configuration of card readers and middleware software for these card readers. The administrator who is configuring BMC Atrium Single Sign-On for CAC authentication is assumed to be familiar with these topics.

CAC certificate usage

In order for CAC authentication to function, the BMC Atrium Single Sign-On server must be prepared with the signer certificates of the identity certificates. These certificates are be presented to the server for authentication.

The certificate for the Issuer must be imported into the BMC Atrium Single Sign-On server's truststore before the clients can send their certificates. The server provides a list of certificates that are trusted. When a request is received for a client certification and there are multiple trusted certificates available, you can select the certificate that you want to use.

For example, when Firefox receives a request for a client certificate and multiple trusted certificates are provided by the list sent from the server, a User Identification Request popup is displayed which allows the user to select a certificate.

Note

For a single user test, the user's certificate (the certificate signed by the Issuer) could be imported into the truststore. However, if this method is used, then every user's certificate must be imported into the truststore.

Certificate signed by the Issuer

For example, the following certificate is signed by the Issuer (C=TX, O="BMC Software, Inc.", CN=AtriumSSO):

Owner: C=TX, O="BMC Software, Inc.", OU=AtriumSSO, CN=GoodSSO
Issuer: C=TX, O="BMC Software, Inc.", CN=AtriumSSO
Serial number: 56acad6af0be9e08
Valid from: Sun Feb 20 17:04:30 CST 2011 until: Tue Feb 19 17:04:30 CST 2013
Certificate fingerprints:
        MD5: 4A:D6:7C:82:E4:2F:18:0B:8C:48:72:50:E2:56:02:5F
        SHA1: 96:9E:6F:DD:A1:41:9C:F5:BD:4A:CC:9E:8B:79:41:6E:4C:A2:C9:69
        Signature algorithm name: SHA1withRSA
        Version: 3

Certificate for the Issuer

For example, the following certificate is the certificate for the Issuer:

Owner: C=TX, O="BMC Software, Inc.", CN=AtriumSSO
Issuer: C=TX, O="BMC Software, Inc.", CN=AtriumSSO
Serial number: 49b6786d72bb8c34
Valid from: Thu Oct 15 16:01:31 CDT 2009 until: Thu Apr 21 16:01:31 CDT 2016
Certificate fingerprints:
        MD5: 81:85:78:CD:80:6A:C1:55:09:7A:FB:79:35:9F:06:5C
        SHA1: 0D:2B:E2:90:ED:9E:24:39:19:B0:93:2F:15:87:3C:8D:F6:D0:03:3D
        Signature algorithm name: SHA1withRSA
        Version: 3

To set up CAC to use for authentication

BMC Atrium Single Sign-On supports using CACs through the ActivClient software from ActivIdentity. See the ActivClient documentation for the configuration steps needed for clients to use CACs, card readers, and browser setup.

Modify the Tomcat server
Import DoD CA certificates
Set up CAC certificates
If using OCSP, enable OCSP for the server

Modify the Tomcat server

Before setting up CAC authentication, the Tomcat server hosting the BMC Atrium Single Sign-On 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 CACs and the Online Certificate Status Protocol (OCSP) server.

To modify the Tomcat server

Stop the BMC Atrium Single Sign-On Tomcat server.
Edit the following file:
<installationDirectory>/BMC Software/BMC Atrium SSO/tomcat/conf/server.xml
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:
<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
     maxThreads="150" scheme="https" secure="true"
     clientAuth="false" sslProtocol="TLS"
     keystoreFile="C:\Program Files\BMC Software\BMC Atrium SSO\tomcat\conf\keystore"
     keystorePass="internal4bmc"
     truststoreFile="C:\Program Files\BMC Software\BMC Atrium SSO\tomcat\conf\cacerts.p12"
     truststorePass="changeit" />
Change the clientAuth attribute from "false" to "want".
clientAuth="want"
The clientAuthattribute 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" />

Import DoD CA certificates

The DoD CA certificates appropriate for your CACs must be imported into the BMC Atrium Single Sign-On 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 CACs 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

Add the bin directory to the PATH environment variable.

When BMC Atrium Single Sign-On 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.
To add the location, run the following command:

(UNIX) export PATH=<installationLocation>/BMC Software/BMC Atrium SSO/jdk/bin:$PATH
(Microsoft Windows) set PATH=<installationLocation>\BMC Software\BMC Atrium SSO\jdk\bin;%PATH%
Copy the DoD CA certificate file into the following directory:
<installationDirectory>/BMC Software/BMC Atrium SSO/tomcat/conf
Use the keytool utility to import the certificate into the truststore using the following parameters:
keytool -importcert -keystore cacerts.p12 -storepass changeit -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.
Accept the certificate at the prompt.
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 Single Sign-On truststore.
- If the LDAP server requires a client certificate, export the BMC Atrium Single Sign-On certificate and import it into the LDAP server's truststore before enabling CAC authentication.
- If CA signed certificates are used for LDAPs, import the CA signed certificate and any intermediate signing certificates into the truststores instead.
If you plan to use OCSP for authentication, import the OCSP responder certificate in the BMC Atrium Single Sign-On truststore with the alias, AtssoOCSP.
Restart the Tomcat server.

Set up CAC certificates

This topic provides instructions for setting up CAC certificates to use for CAC authentication.

To set up CAC certificates

The macro unmigrated-inline-wiki-markup from Confluence is no longer available.

Note

You can provide parameter information for OCSP authentication, CRL authentication, or both. BMC does not recommend using the CRL approach due to the performance load experienced with the ever-increasing length of CRL lists.

CAC certificate parameters

When adding or editing a CAC certificate module, the following options are available:

The macro unmigrated-inline-wiki-markup from Confluence is no longer available.

Field	Parameters	Description
Name		Name for the Certificate and CAC authentication.
Use OCSP		Click Use OCSP in order to use the OCSP responder. BMC recommends that you use OCSP for validation. Note: The clock skew between the BMC Atrium Single Sign-On server and the OCSP server must not be greater than 15 minutes. Otherwise, the certificate authentication fails. See Clock-skew-too-great-for-CAC-authentication.
Certificate Field for User Profile		Select one of the options. Options are Subject CN (Common Name attribute of the Subject DN), Subject DN (Distinguished Name), Subject UID (UID attribute of the Subject DN), Email, None, Other.
Forwarded Certificates		When running behind a load balancer or reverse proxy, the verification of ownership of the private key is not possible thru the SSL/TLS connection. Because of this verification restriction, the BMC Atrium Single Sign-On server requires that the fronting server be listed as a trusted host from which forwarded certificates can be trusted.
	Forwarded Certificate List	This is the list of trusted host name that you add via the Trusted Host Name field. To delete a certificate, select the trusted host name and click Remove.
	Trusted Host Name	Enter the name of a host from which a forwarded certificate can be trusted.
	Certificate HTTP Header Name	Enter the name of the HTTP header that the forwarded certificate can be passed under.
Certificate Revocation Lists (CRL)	Use CRL	Select Use CRL to use a Certificate Revocation List (CRL). Note: BMC does not recommend using the CRL approach due to the performance load experienced with the ever-increasing length of CRL lists.
	LDAP Server Where Certificates are Stored	Provide the Host and Port for the LDAP server where the certificates are stored. The host name must end with a colon following by the port number for the LDAP server.
	LDAP Start Search DN	Enter the DN of the node. The DN of the node starts the search within the LDAP server. To connect with the LDAP server, you must have sufficient privileges to perform the search.
	LDAP Server Password Confirm LDAP Server Password	Provide and confirm the password to connecting with the LDAP server.
	Check CA with CRL	When verifying a certificate, the CA certificate used to sign the certificate can also be verified in the CRL.
	Use SSL/TLS	If you are using SSL, the LDAP server certificate must be imported into the BMC Atrium Single Sign-On truststore so that SSL can connect with the LDAP server.
Trusted Certificates		Browse on your desktop to upload the trusted certificates file. Once the file is upload and in the trusted certificates list. You can also select the file, and click Remove to remove the file.

If using OCSP, enable OCSP for the server

If you plan to use OCSP for authentication, enable OCSP for the server.

Verify that the OCSP responder certificate was imported into the BMC Atrium Single Sign-On truststore.
On the BMC Atrium SSO Admin Console, click Edit Server Configuration.
In the Online Certificate Status Protocol field, select Enable OCSP and provide the server URL.
Click Save.

Where to go from here

Administering for information about authentication, users, and groups.