CAC Authentication

Download this manual as a PDF file

This section describes how SL1 supports Common Access Card (CAC) authentication. The Client Certificate & CAC Authentication page (System > Settings > Authentication > Admin SSL Certificates, or System > Settings > Authentication > SSL Certificates in the classic SL1 user interface) allows you to define a check for SSL certificate that controls whether the login page is displayed to the end user.

This feature is primarily used to authenticate Common Access Card (CAC) users against a Department of Defense (DoD) issued server-side certificate; however, based on your business needs, this feature can also be used with your own client/server certificates.

You can use CAC authentication to log in to either the current SL1 user interface ("AP2") or the classic SL1 user interface. Follow the steps described in this section to configure your CAC authentication, regardless of which user interface you use.

Currently, SL1 does not support client-side certificate authentication for login to the console, either through SSH or through a keyboard connected to the appliance.

Use the following menu options to navigate the SL1 user interface:

  • To view a pop-out list of menu options, click the menu icon ().
  • To view a page containing all of the menu options, click the Advanced menu icon ().

Using CAC Authentication

SL1 supports CAC authentication. The Client Certificate & CAC Authentication page allows you to define a check for SSL certificate that controls whether the login page is displayed to the end user. This feature is primarily used to authenticate Common Access Card (CAC) users against a Department of Defense (DoD) issued server-side certificate; however, based on your business needs, this feature can also be used with your own client/server certificates.

The CAC is a United States DoD smartcard issued as standard identification for Active Duty Military personnel, reserve personnel, civilian employees, and eligible contractor personnel. A User Principal Name (UPN) is recommended, and in some instances required, when using CAC.

CAC provides applications with a more secure way to authenticate the identity of a user, application, or device. However, even if a user authenticates with a certificate, it does not mean that they user is authorized to access the requested data. For more information on authentication and authorization, see the DoD documentation on authentication and authorization for DoD web servers.

DoD has implemented an external interoperability strategy for secure information sharing with external partners. Some DoD industry partners have implemented corporate PKIs, and others have obtained certificates from approved commercial PKIs. Some DoD international allied and coalition partners also have established PKIs to issue certificates to their personnel. Systems and applications with user populations that hold approved external credentials should be configured to accept those credentials rather than requiring the users to obtain Common Access Cards (CACs) or External Certification Authority (ECA) certificates. For the complete list of DoD approved external PKIs and interoperability tools, see the DoD documentation on interoperarability.

DoD policy requires that external credentials have an assurance level of medium hardware or higher, so systems accepting external credentials must have an assurance level enforcement capability. Depending on technology, this can be accomplished through use of the Interoperability Root CAs (IRCAs) or implementation of a local certificate policy object identifier (OID) filtering solution such as the DoD PKE Trust Anchor Constraints Tools (TACT). For a complete list of approved partner OIDs, see the DoD documentation on the approved assurance levels from external partner PKIs.

Systems and applications typically have configuration properties that control security settings related to PKI functionality. Security settings should be configured to support all desired PKI functions and comply with DoD authentication policy.

SL1 allows you to configure appliances that provide the user interface (Administration Portal, All-In-One Appliance, or the Database Server) for use with DoD certificates or your own certificates.

The CAC is used as the user's authentication to SL1. If the Authentication Profile (System > Settings > Authentication > Profiles) contains both the "CAC/Client Cert" and "EM7 Login Page" credential sources and a CAC is not presented or is invalid, then the ScienceLogic login page is presented to the end user.

You can use CAC authentication to log in to either the current SL1 user interface ("AP2") or the classic SL1 user interface. Follow the steps described in this section to configure your CAC authentication, regardless of which user interface you use.

NOTE: Currently, SL1 does not support client-side certificate authentication for login to the console, either through SSH or through a keyboard connected to the appliance.

Prerequisites

To use client certificate authentication with SL1, you must first meet the following requirements:

  1. Organizations must be created and configured. For more information, see Creating and Editing Organizations.
  2. An LDAP or AD Credential must be configured with a Service Account that has the appropriate permissions to query AD, typically read access.
  3. Create one or more User Policies if you will use SL1 authentication. You do not need to configure user policies if you are using Active Directory (AD) or LDAP. For more information, see Creating a User Policy.
  4. If you are using LDAP or Active Directory as your user store, you must configure this as your Authentication Resource before setting up your Authentication Profile. For more information, see Authentication Resources.
  5. Configure an Authentication Profile for CAC authentication. When setting up your Authentication Profile for CAC, align the "CAC/Client Cert" credential with the profile as the first credential source. You can align the EM7 Login Page as a secondary credential source for administrator access, but this is not required. For more information, see Creating an Authentication Profile.
  6. Configure an emergency account ("break glass" account) for the Database Server. Because CAC will work only with the Database Server's DNS name, an emergency account ensures that the em7admin account is used only as a last resort.
  7. Go to the Authentication Profiles page (System > Settings > Authentication > Profiles). Select the wrench icon ( ) for the default profile. In the Authentication Profile Editor page, in the Aligned Credential Sources field, delete any existing CAC/Client Cert credentials.
  8. Your users must have either:
  • Valid CACs with valid client-side certificates already loaded onto the cards, or
  • Valid client-side certificates installed in their web browser.
  1. If CACs are used, the browser through which the user logs on to the user interface must be able to read security certificates from the cards.

  2. The Administration Portal, All-In-One Appliance, or the Database Server will request a certificate from the CAC or client web server only when the appliance uses HTTPS. In SL1 12.2.0 and above, the use of HTTPS is enforced by default. In SL1 versions prior to 12.2.0, you must go to the Behavior Settings page (System > Settings > Behavior), and select the Force Secure HTTPS setting checkbox.

    In SL1 12.2.0 and above, the Force Secure HTTPS setting does not appear as an option on the Behavior Settings page.

  3. On the SSL Certificates page (System > Settings > Authentication > Admin SSL Certificates, or System > Settings > Authentication > SSL Certificates in the classic SL1 user interface), you must install the certificate chain in PEM format on the Administration Portal, All-In-One Appliance, or the Database Server. A certificate chain usually includes a root CA certificate and an intermediate certificate. Your organization might require multiple intermediate certificates to provide access to all users. To learn more about importing a certificate, see the section Importing an SSL Certificate.

    4. If you want to extract part of the Common Name to customize the username that is displayed in SL1 after CAC authentication, you can edit the ScienceLogic configuration file to customize the displayed username. You do not need to do this if you are using the msUPN. For more information, see Extracting the Common Name from a Certificate for Authentication.

  4. In the Client Certificate & CAC Authentication page (System > Settings > Authentication > CAC Client Cert Auth, or System > Settings > Authentication > CAC/ClientCert Auth in the classic SL1 user interface), you must configure the server-side certificate and test it against your client-side certificate. For more information, see Defining the Client Certificate Chain.

Importing SSL Certificates

Secure Sockets Layer, or SSL, is a protocol for securely transmitting data via the Internet. SSL uses a private key to encrypt data to be transferred over an Internet connection. In SL1, you can import server-side SSL certificate files, including DoD certificate files used in CAC authentication, to the Administration Portal, All-In-One Appliance, or the Database Server.

Note the following:

  • You must have one root certificate and one certificate for each intermediate authority in the client certificate chain. If you have users with CACs issued by different intermediate authorities, you must import SSL certificates for all possible client authentication chains into SL1.
  • All SSL certificates must be in PEM format.

  • You can test your SSL certificate files by using the following command, where <certificate_file_name> is the full name of the certificate file:

    • openssl x509 -text -noout -in <certificate_file_name>

It is a best practice to check each certificate file before attempting to import the file. If you encounter an error, resolve that error before you continue.

To import an SSL certificate for CAC authentication:

  1. Go to the SSL Certificates page (System > Settings > Authentication > Admin SSL Certificates, or System > Settings > Authentication > SSL Certificates in the classic SL1 user interface).
  2. In the SSL Certificates page, click the Actions menu. Select Import PEM Certificate File. The Import Certificate File (PEM format) modal appears.
  3. In the Import Certificate File (PEM format) modal, enter the following:
  • Description. Description of the certificate.
  • CA File. Browse for the server-side certificate file on your local computer.
  1. Click the Save button to load the certificate to the Administration Portal, All-In-One Appliance, or the Database Server.
  2. Repeat these steps for each certificate file you want to import. When finished, verify that all of your certificates appear in the listing shown on the SSL Certificates page (System > Settings > Authentication > Admin SSL Certificates, or System > Settings > Authentication > SSL Certificates in the classic SL1 user interface).

A best practice is to make note of the value in the Hash field shown for each certificate and verify that the hash values match the symlink files in the /var/lib/em7/certs directory on the appliance after completing the configuration of your client certificate chain. You will use these hash values in Verifying SSL Certificate File Import and Resolving Issues.

Extracting the Common Name from a Certificate for Authentication

By default, the certificate configuration file (em7_certificate.conf) is configured to display the full common name (CN) of the CAC user as the username in SL1 after authentication. If this meets your requirements, then you do not need to update the configuration file and can skip this section.

If you are using the Microsoft User Principal Name (MS UPN) in your certificates, you do not need to make any edits in the configuration file.

However, if you require that SL1 use only a portion of the CN, then you can edit the certificate configuration file to parse out a username from the CN in the certificate.

For example, in some instances you might want to use an employee's ID number as the username. To do that, you must edit the Nginx configuration file.

To do so:

  1. Log in to the console of the SL1 appliance as the root user.
  2. Navigate to the directory /etc/nginx/conf.d/ :

cd /etc/nginx/conf.d/

  1. Open the file em7_certificate.conf with a text editor like vi:

vi em7_certificate.conf

  1. Modify the file to extract the CN from the full Distinguished Name (DN) found in the certificate based on how you want to map the username to an LDAP system or how you want the usernames to look if you are using SL1 internal as the backend of your authentication configuration.

    This is the default configuration of the file:

    # Create the Username for EM7 to use from the Certificate
# Default: Pull the Common Name from the DN.
map $ssl_client_s_dn $ssl_client_username {
~/?CN=(?<CN>[^/,]+) $CN;
}

    Modify the string to extract the name. The following is a regular expression that extracts the CN from the full DN) found in the certificate:

    map $ssl_client_s_dn $ssl_client_username { ~/CN=[A-Z\.]+(?<num>[0-9]+) $num; }

  1. Save and quit (:wq) the file.

Defining the Client Certificate Chain

After importing your SSL Certificates, you must consolidate the SSL PEM certificates into a combined file (emt_combined.crt). On the CAC/ClientCert Auth menu, select all of the desired SSL PEM certificates. After saving, SL1 will update the em7_combined.crt file with all of the selected SSL PEM certificates. SL1 will then use only the selected PEM certificates for validating and authenticating users.

You can also define some custom settings for client-side certificate authentication. You can define error messages that are displayed to the end user if authentication fails. Optionally, you can also define IP addresses in this modal for which the user interface will not perform certificate authentication, if you have not already created an Authentication Profile for this purpose. See Accessing the Appliance without CAC Authentication for more information.

When authentication is successful, the user interface displays the ScienceLogic Login page to the user.

To define the authentication settings:

  1. Access the user interface with your CAC or a browser with your client-side certificate installed.
  2. Go to the Client Certificate & CAC Authentication page (System > Settings > Authentication > CAC Client Cert Auth, or System > Settings > Authentication > CAC/ClientCert Auth in the classic SL1 user interface).
  3. Supply a value in each of the following fields:
  • Root CA Certificates. Select all root and intermediate certificates that make up the chain from a list of certificates installed on the SSL Certificates page (System > Settings > Authentication > Admin SSL Certificates, or System > Settings > Authentication > SSL Certificates in the classic SL1 user interface). Your client-side certificate will be authenticated against the selected server-side root and intermediate certificates.
  • Auth Failure Message. Enter text for the error message that appears to users if authentication fails.

    • You cannot save your authentication settings until you enter text in the "Auth Failure Message" field.

  • Ignore Networks. In this field, you can enter a list of networks and hosts from which certificate authentication is not required. During each login, the platform will compare the client's IP address to the list entered in this field. If the client's IP address is included in this field, SL1 will not require certificate authentication from that client.

    If you are using Authentication Profiles to configure access from specific resources from which certificate authentication is not required, you do not need to use the Ignore Networks field. For more information, see Accessing the Appliance without CAC Authentication.

  • In the Ignore Networks field, you can enter one or more IP addresses, each separated by a new-line character (press the <Enter> key).

  • In the list of IPs to ignore, you can enter only the first octet, only the first and second octet, only the first, second, and third octet, or all four octets. SL1 will interpret the entry as if the rightmost octet is followed by * (asterisk).

    • For example:

    • 192.168.10.142 will allow a single host to log in to the user interface without certificate authentication

    • 192 behaves the same as entering 192*. This will allow all hosts included in 192.0.0.1 through 192.254.254.254 to log in to the user interface without certificate authentication
    • 192.168.10.24 behaves the same as entering 192.168.10.24*. This will allow all hosts 192.168.10.24, 192.168.10.240, 192.168.10.241, 192.168.10.242, 192.168.10.243, 192.168.10.244, 192.168.10.245, 192.168.10.246, 192.168.10.247, 192.168.10.248, and 192.168.10.249
  1. Click the Save button to save your settings. The user interface displays the message:

Settings Saved Successfully. Configuration must be tested in order to take effect.

Do not click the Test link at this time.

Verifying SSL Certificate File Import and Resolving Issues

After you have imported your SSL certificates and configured your client certificate chain, it is important to verify the your certificate files were imported correctly and are valid in SL1.

To verify that your SSL certificate files were imported correctly:

  1. Either go to the console of the SL1 appliance where you imported the SSL certificates, or use SSH to log in.
  2. Navigate to the /var/lib/em7/certs directory. At the shell prompt, enter:

    3. ls -l

  3. Review the list of hash symlink files in the directory and compare them to the list of certificates on the SSL Certificates page. Ensure that the hash values shown in SL1 match the hash symlink files. Note that the hash symlink in the /var/lib/em7/certs directory (in blue text) for a certificate file is appended with ".0", as shown in the image below.

    4. All of the following must be true. If any of these are not true, then the certificate file was not imported and saved correctly in SL1:

    • One hash symlink file should exist in the directory for each of the imported certificate files.
    • The file size of the "em7_combined.crt" file is equal to the combined file sizes of all of the certificate (.pem) files. (The file "em7_combined.crt" is not equal to the "em7_default.crt" file.)
    • When you view the contents of the "em7_combined.crt" file using cat or similar command, the file is the concatenation of all of the certificate (.pem) files. NGINX references the "em7_combined.crt" file as the file containing the client certificate chain.
  4. If any of the conditions listed above are not true, then the certificate file was not imported and saved correctly in SL1. To resolve the problem:
    1. Log in to the SL1 appliance user interface.
    2. Go to the Client Certificate & CAC Authentication page (System > Settings > Authentication > CAC Client Cert Auth, or System > Settings > Authentication > CAC/ClientCert Auth in the classic SL1 user interface).
    3. Edit the Auth Failure Message field. Make a change to the section.
    4. Click Save.
    5. Repeat steps 1-3 to verify your certificate files.

Clearing the SL1 Cache and Restarting NGINX

Before you proceed to testing the configuration, you must clear the SL1 cache, restart nginx, and close any browsers you have open. This will ensure the best outcome when testing.

  1. Log in to the user interface on the SL1 appliance.
  2. Click on the Toolbox button () and choose Misc > Clear SL1 System Cache.
  3. Log out of the SL1 appliance.
  4. Either go to the console of the SL1 appliance where you imported the SSL certificates, or use SSH to log in to the appliance.
  5. Run the following command to restart nginx:

    6. sudo systemctl restart nginx

     

  6. Close any open browsers that have been used to access the appliance.

Testing the Configuration

After you define the certificate authentication settings, you must test your client-side certificate against the server-side certificate you selected in the Root CA Certificates field. Testing your configuration is required to prevent an incorrect configuration from preventing administrator access to the user interface. If the test is successful, the certificate authentication settings will be applied. If the test is unsuccessful, the certificate authentication settings will not be applied.

To test certificate authentication settings:

  1. With your CAC inserted in the reader, access the user interface of your SL1 appliance using the IP address or domain name defined in the AP Hostname Pattern field of the CAC Authentication Profile (System > Settings > Authentication > Profiles). Log in with an administrator account.
  2. Go to the Client Certificate & CAC Authentication page (System > Settings > Authentication > CAC Client Cert Auth, or System > Settings > Authentication > CAC/ClientCert Auth in the classic SL1 user interface).

  3. After defining the certificate, you will see the following message at the top of the pane:

    Configuration must be tested in order to take effect: TEST.

  4. Click the TEST link. SL1 will attempt to authenticate your client-side certificate against the selected server-side certificate.

  5. If the test authentication is successful, SL1 will display the following message at the top of the pane and end users with the appropriate client certificate or CAC can now access the user interface using client certificate authentication:

    Configuration verified and enabled.

  6. A new field, Client Cert / CAC Auth, appears with a default value of Allowed. Do not edit this field.

  1. Set the Certificate User Field to "Common Name" (default) or "MS UPN".

    2. If you are using LDAP or Active Directory (AD) for user authentication, set this field to "MS UPN".

  2. Select the Save button to save the setting in the Client Cert / CAC Auth field.

  3. If the test authentication is unsuccessful, the user interface will display the following message at the top of the pane. The settings will not be applied, and client certificate authentication will not be used until the problem is corrected:

    ERROR: configuration was not successfully tested with CAC or Client Certificate.

    If you experience the error above, double-check the following: verify there are not any simple mistakes by reviewing any information you manually entered; check to see if there is a mismatch between the certificate chain installed in nginx versus what the browser uses; make sure the cert file names do not contain spaces or blanks in the file name.

Troubleshooting CAC Authentication

There are a few common issues you might experience while testing CAC authentication. If your test is unsuccessful, review the following troubleshooting steps.

Failed to Identify Personal Identity Verification (PIV) Card

If you receive the "Failed to identify PIV card" message, verify the following:

  • All root and intermediate certificates have been uploaded in a PEM format.
  • All root and intermediate certificates have not expired and are configured properly.
  • The client certificate has not expired.
  • Customer username information is in the Microsoft User Principal Name (MS UPN and not the Common Name (CN).

Failed CAC Authentication After Disaster Recovery (DR) Failover

If your CAC authentication testing fails after DR failover, verify the following:

  • The DR node domain has been added to the Auth Profile for pattern matching.
  • The DR has all of the required certificates. (You might be required to manually upload and save the certificates again.)

    • For more information, see Disaster Recovery with Two Appliances.

Failed CAC Authentication After Setting Up High Availability (HA)

Assuming you have deployed an SL1 distributed system with one Database Server and two or more Administration Portals and your CAC authentication testing fails after setting up HA, you must ensure the following:

  • The first Administration Portal where you configured CAC is working and you authenticated with CAC before verifying that the second or third Administration Portal actually works. You should not have the CAC/Client Cert in the aligned credential source on the default profile but in a new profile created for CAC only.

    ScienceLogic suggests having at least two profiles (a default profile and a CAC profile). You should enter an AP Hostname Pattern on the CAC profile but keep the AP Hostname Pattern blank on the default profile.

  • Upon successful CAC login on the first Administration Portal, you will notice that any login attempts to the second or third Administration Portal will fail. For this, you need to first verify that the content of the /var/lib/em7/certs contains the PEM files that are identical to the first Administration Portal. You must also ensure that the hash files representing your PEM files are identical to the first Administration Portal and that the combined file is identical to the first Administration Portal.
  • Once verified, restart nginx on the second and third Administration Portals and ensure that nginx is running correctly.
  • Verify that you can log in with CAC from the second or third Administration Portals as you have done with the first Administration Portal.

    For more information, see High Availability with Two Appliances

Accessing the Appliance without CAC Authentication

In certain circumstances, you might need to access your SL1 Appliance without using CAC authentication. For example, the following are some reasons you might want to use another authentication type:

  • For use during initial setup
  • For appliance access when a certificate has expired
  • For maintenance or administrator accounts
  • For certain internal networks that will not require certificate authentication

You can configure the appliance to accept a login in these cases in two ways:

  • By configuring an Authentication Profile to use an alternative authentication resource (for example, EM7 Internal) for certain networks or hosts. For more information, seethe section on Authentication Profiles.
  • By using the Ignore Networks field on the Client Certificate & CAC Authentication page (System > Settings > Authentication > CAC Client Cert Auth, or System > Settings > Authentication > CAC/ClientCert Auth in the classic SL1 user interface). For more information, see Defining the Client Certificate Chain.

Special Circumstance: Multiple Levels of Intermediate Certificates

By default, SL1 is configured to handle the typical certificate hierarchy, which comprises three levels: root, intermediate, and client certificates. This represents a depth of 2 from the root to the client certificate. If your organization will use CAC authentication in which you have multiple levels of intermediate certificates in the hierarchy, you will need to change this setting (ssl_verify_depth) as described in the procedure below.

To update the value of ssl_verify_depth:

  1. Log in to the console of the ScienceLogic appliance as the root user.
  2. Navigate to the directory /etc/ngnix/conf.d/ :

cd /etc/ngnix/conf.d/

  1. Open the file em7ngx_web_ui.conf with a text editor like vi:

vi em7ngx_web_ui.conf

  1. Edit the ssl_verify_depth value to be the depth from client certificate to the root certificate (for example, 3):

ssl_verify_depth 3;

  1. Save and quit (:wq) the file.