Enabling smart card authentication

Guardium smart card support meets the United States government mandate that all vendors must support multi-factor authentication for user access. Smart card authentication is supported only for access to the web-based Guardium user interface (UI).

Before you begin

Details of the multi-factor authentication requirement are found in the Identification and Authentication (Organizational Users) (IA-2) section the Security and Privacy Controls for Federal Information Systems and Organizations (NIST Special Publication 800-53) document. NIST 800-53 is available through the NIST website: https://www.nist.gov.

Government applications refer to Personal Identification and Verification Cards (PIV). Civilian applications refer to Common Access Cards (CAC). PIV and CAC cards have different certificate authorities, but the cards are otherwise the same.

Guardium smart card support meets the HIGH confidence PIV assurance level. PIV assurance is described in the PIV Cardholder Authentication (6) section of the Personal Identity Verification (PIV) of Federal Employees and Contractors (FIPS Publication 201-2) document. FIPS 201-2 is available through the NIST website: https://www.nist.gov.

In addition to the configuration steps described here, users require,

Access to the Guardium UI from a web browser that can access the smart card certificate.
A valid PIV or CAC card.
A smart card reader.
Tip: Admin and accessmgr users can log into the Guardium® system without using a smart card. For more information, see the CLI command store system admin-only.

You can either associate existing Guardium users or create users to associate with smart cards. You can also import user definitions from an LDAP server and edit the smart card user name field without losing any related settings. After you configure your site to use smart card for authentication, Guardium uses the smart card credential only to establish SSL/TLS communication (Guardium uses HTTPS). For more information about creating users and access management, see Managing access to Guardium.

Note: While smart card authentication is used to authenticate, you still need to set user access control (that is, which Guardium modules a user can access) through access management.

About this task

This task describes how to associate the information on a smart card with a Guardium user.

Procedure

Log in as Admin from a central manager or standalone machine.
Browse to Setup > Tools and Views > Portal.
From Authentication Configuration, select Smart Card.
In Regex Match Pattern, use a regular expression (regex) to match the user information on the smart card, for example,
```
CN ?= ?(.*?), ?OU ?= ?Test Agency, ?OU ?= ?Test Department, ?O ?= ?Test Government, ?C ?= ?US
```
In this example, both patterns match the mapping for the client certificate. Pattern 1 is more exact, but with pattern 2, you can edit the pattern to match your needs. If you are not familiar with the data on the smart card, work with someone who can write efficient mapping patterns.
- Pattern 1:
```
CN ?= ?(.*?), ?OU ?= ?Test Agency, ?OU ?= ?Test Department, ?O ?= ?Test Government, ?C ?= ?US
```
- Pattern 2:
```
CN ?= ?(.*?)
```
  Both of the examples get the value for CN attribute in the certificate subject (which you can see by examining the certificate details in the browser). Configuring this pattern correctly is probably the most important step in making sure that smart card authentication is successful.
  
  Note: The Guardium regex validation tool cannot validate the regex for smart card.
  
  Tip: You can update the regex values for smart card authentication with the SMART_CARD_MAPPING_REGEX parameter of the modify_guard_param API command. For more information, see Smart card parameter.
Upload or add a trusted certificate from a certificate authority (CA) to your web server truststore.
You can obtain a certificate either directly from a customer or by exporting it from a smart card by using a certificate management tool such as certMgr.exe or OpenSSL.
Note: If you do not have the root certificate of the CA that signed the certificates on the smart cards, export a root certificate from a CA-signed user certificate or a smart card that contains one.

Important: If you enable Online Certificate Status Protocol (OCSP) validation, you must upload valid OCSP client certificates. If the client certificates are not OCSP-enabled, you cannot access the Guardium system and the admin user cannot revert the setting. Valid OCSP certificates indicate Method #1: Online Certificate Status Protocol and include a valid URI
1. If trusted certificates are available, click Trusted Certificates.
  Select a certificate to use for smart card authentication. The signing chain lists a series of signing authorities. The best certificate to select is usually the intermediate authority above the user certificate.
2. If you do not have a certificate available, click Add Trusted Certificates and then browse to the certificate location and click Upload to import the certificate.
  In general, you want to import the public root certificate of a trusted CA. This is the most common source of a root certificate in environments that already have a smart card infrastructure and a standardized approach to smart card distribution and authentication.
If needed, select Enable OCSP check to enable OCSP validation.
When the OCSP check is enabled, Guardium communicates with the OCSP responder ensures that the certificate in the truststore is valid. If the certificate is unknown or revoked, a user receives an error message when they attempt to log in to Guardium.
Note: Upload the OCSP-enabled certificates before you select Enable OCSP check.
Click Save to save your work. However, you aren't finished yet. You still need to distribute the authentication configuration to managed units on your network and then enable smart card authentication from the CLI.
On a central manager, browse to Manage > Central Management > Central Management.
1. On the Central Management page, select the managed units that you want to include for smart card authentication.
2. Click Distribute Authentication Config and then check the results to make sure that the selected managed units were updated successfully.
3. Distributing the authentication configuration to the managed units can take up to an hour. To distribute the authentication configuration immediately, click Refresh.
Next, turn on smart card authentication from the Guardium CLI.
To turn smart card authentication on or off, use the following CLI command,
```
store system websmartcard [on | off]
```
Note: Whenever you run this CLI command, the GUI automatically restarts. When you disable smart card authentication, the GUI restarts with the system that uses local authentication.

To check the status of smart card authentication, use the following CLI command,
```
show system websmartcard
```
For more information, see store websmartcard in System CLI commands.
Optional: The admin or accessmgr can log into the Guardium system without a smart card by using a separate login page.

Run the CLI command store system admin-only on. Then, access the login page by appending /admin to the URL of your Guardium system. Example: https://www.[your_guardium_system's_domain_name].com:[port_number]/admin. Log in using your credentials.

For more information, see store system admin-only in System CLI commands.

What to do next

After smart card authentication is enabled, you can access the site with a valid smart card (such as PIV or CAC). Enter the card into the card reader. Depending on how your smart card is configured, you might be asked to enter the PIN associated with the smart card.

After you swipe the smart card:

A list of certificates displays. Select a certificate from the list.
If requested, enter your PIN.
If Guardium recognizes the smart card certificate, the Guardium dashboard opens. If the certificate is invalid (or revoked), the user receives an authentication error.

Troubleshooting

After you enable smart card authentication, you get an error from the Guardium URL.
Diagnosis: Most likely, your configuration of the matching regular expression is incorrect or you don’t have a valid certificate on the card.
You created a matching regex and it does not seem to be working. You know that Guardium has a regex validation tool and use it, thinking that if it works in the tool, it's a good regex pattern. Unfortunately, while the test is successful in the tool, the regex pattern doesn't work for smart card configuration.
Diagnosis: The regex tool determines if regex can find an expression inside a text paragraph. When configuring a smart card, regex extracts a piece of text from the certificate (displayed in the subject as shown in certificate details), and therefore does not work in this situation.
You didn’t get prompt from the browser to select a certificate.
Diagnosis: Your computer is able to install the card reader and the smart card. A copy of the certificate in the smart card is copied to the certmgr in Windows OS. However, the browser (such as Firefox or Chrome) cannot read the certificate. In other words, browsers on Windows are unable to read the certificate and there is no prompt to choose the certificate.

This is a rare, but known, situation on all browsers on some laptops that were tested. In this case, the issue is with your smart card configuration and not Guardium.

Solution: Contact your smart card administrator.