Using CAC for authentication

BMC Atrium Single Sign-On supports Common Access Card (CAC) authentication. Beyond the scope of this document is acquiring CACs, Department of Defense (DoD) Certificate Authority (CA) certificates, and 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. For basic information about CAC, see Common Access Card.

The following topics are provided:

CAC certificate usage

To enable CAC authentication, you must prepare the BMC Atrium Single Sign-On server with the signer certificates of the identity certificates. You must present these signer certificates to the server for authentication.

The certificate for the Issuer must be imported into the BMC Atrium Single Sign-On server truststore before 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 multiple trusted certificates are 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 pop-up window is displayed, allowing the user to select a certificate.

Note

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

Example of a certificate signed by the Issuer

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

Example of a certificate for the Issuer

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 configure CAC for authentication

BMC Atrium Single Sign-On supports using CACs through the ActivClient software from ActivIdentity. See the ActivClient documentation for information about configuring CACs, card readers, and browsers.

Perform the following steps to configure CAC:

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

Modifying the Apache Tomcat server

Before you configure CAC authentication, you must configure the Apache Tomcat server hosting the BMC Atrium Single Sign-On application to ask clients for certificates. You must also configure the Tomcat server truststore with the root certificates for the CACs and the Online Certificate Status Protocol (OCSP) server.

Stop the Apache Tomcat server that is being used for BMC Atrium Single Sign-On.
Open 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 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 Single Sign-On–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 CACs must be imported into the BMC Atrium Single Sign-On server truststore before you can use CAC for authentication. Importing the certificates allows the server to send the appropriate query to the client for enabling it to return the correct certificate. Refer to the documentation from the supplier of your CACs for the location from which you can acquire the current root certificates.

You will import certificates into the server truststore (cacerts.p12 ).

To import DoD CA certificates

On the BMC Atrium SSO Admin Console, click Edit Server Configuration.
The Server Configuration Editor is displayed.
On the Certificates tab, select the Certificate Store for which you want to import a Certificate Signing Request (CSR).
The options are KeyStore, TrustStore, SAMLv2 KeyStore, and Session KeyStore.
Select TrustStore from the list.
Click Import.
The Upload Certificate dialog box is displayed. You can upload the certificate using one of the following options:
- PEM Encoded Certificate — Use this option to copy the certificate details.
- HTTPS URL — Enter the host and port from which to capture a certificate.
- DER/PEM/PKCS12 Encoded File — If you want to import a key pair, upload the PEM-encoded DER/PEM files. If you want to import a chain of certificates, upload the PKCS#12 file. When you select the PKCS#12 file, an additional password field is provided to allow you to enter the password for the truststore.
Enter the alias for each certificate or key pair that you are uploading in the truststore.
If Secure Sockets Layer (SSL) is used to communicate with an external LDAP server, import that server's certificate into the truststore:
- Use the Import option.
  Note
  - If the LDAP server requires a client certificate, select the existing BMC Atrium Single Sign-On certificate and click PEM to copy and export it. Then import that certificate 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. For more information about importing CA signed certificates, see Adding and removing a CA certificate.
If you plan to use OCSP for authentication, import the OCSP responder certificate to the BMC Atrium Single Sign-On truststore with the alias AtssoOCSP.
Restart the Tomcat server.

Configuring CAC certificates for authentication

Unknown macro: {multi-excerpt-include}

Note

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

CAC certificate parameters

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

Unknown macro: {multi-excerpt-include}

The CAC Editor has the following parameters:

<[^>]+?>","")"/>

<[^>]+?>","")" class="contextID">

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.

Enable OCSP for the server

If you plan to use Online Certificate Status Protocol (OCSP) authentication, enable OCSP for the server.

To enable OSCP 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

See Administering for information about authentication, users, and groups.