Configuring smart card authentication

Tanium Cloud does not support smart card authentication.

The Tanium™ Console supports smart card authentication. A smart card is physical credential that has a microchip and data, such as secure certificates and keys. Smart cards are also known as common access cards (CAC) and personal identity verification (PIV) cards. Endpoint systems are set up with smart card readers, and end users use their smart card to authenticate and gain access.

Requirements

When smart card authentication is enabled, the Tanium Server and Tanium Module server must reside on separate hosts. All authentication to the Tanium Console requires smart cards unless the authentication request is from one of the following sources:

  • The system hosting the Tanium Server through the local loopback address (127.0.0.1 for IPv4 or [::1] for IPv6).
  • The Module Server connection to the Tanium Server.

Consequently, any additional integrations that you want to automate must reside on one of the two hosts. The following are some examples:

  • SSRS plugin
  • Microsoft Excel plugin (unless using the version that supports smart card authentication)
  • Tanium™ Connect for Lightweight Directory Access Protocol (LDAP) synchronization
  • PyTan
  • Thrid-party security operations center (SOC) websites that query Tanium for data
An air gap deployment with smart card authentication has additional caveats:
  • Links to content that is hosted on the Tanium Server must use the local loopback address. This is because the TDownloader service that downloads content to the Tanium Server cannot present a certificate.
  • Links to Tanium module or shared service imports use both the local loopback address (for the workbench) and the Tanium Module Server fully qualified domain name (FQDN) for the portion of the solution installed on the Module Server.

Create a certificate

Smart card authentication for Tanium Console access depends on the public key infrastructure (PKI) of your organization. You can get started if you have a client certificate that is signed by the root certificate authority (CA) certificate for the domain where the Tanium Server is deployed. Make sure the certificate has the Proves your identity to a remote computer attribute.

Figure  1:  Proves your identity to a remote computer

Create a new certificate file from certificates that you extract from the client certificate. Usually, you need to extract only the root certificate. If this does not work, you might also need to add intermediate certificates to the certificate chain.

Extract the certificates

  1. Get a copy of a client certificate file that is signed by the root CA certificate for the domain. See Figure  1.
  2. On a Windows endpoint, double-click the certificate file to open it in the Windows Certificate Snap-In.
  3. On the Certification Path tab, select the root certificate. In this example, DigiCert is the root certificate.
  4. Go to the Details tab and click Copy to File to display the Certificate Export Wizard.
  5. Select Base-64 encoded X.509 (.CER).
  6. Select a folder and specify a file name such as example1.cer.
  7. Review the settings and click Finish to save the certificate.
  8. If your deployment has intermediate CA certificates, repeat these steps to extract them. Go to the Certification Path tab and select the next certificate in the chain. In the following example, DigiCert SHA2 High Assurance Server CA is the next certificate. Export this certificate with a name such as example2.cer.





Create a new certificate file

  1. Create a file named cac.pem.
  2. Copy and paste in the contents of each certificate in the chain into the file.







    • Each section of the certificate file must start with -----BEGIN CERTIFICATE----- and end with -----END CERTIFICATE-----.
    • There must be only one carriage return between each certificate in the chain.
    • There must be no extra white spaces or carriage returns at the beginning or end of the file.
    • The preceding example shows the root certificate last, which is a convention that Tanium Support uses.

  3. Save the file.

Appliance: Configure CAC

Add your CAC account user name (EDIPI) as a Tanium Administrator before enabling CAC.

Step 1: Install the certificate

Upload and install the certificate:

  1. Use SFTP to copy the certificate file (PEM format) to the /incoming directory on the Tanium Server appliance.
  2. Sign in to the TanOS console as a user with the tanadmin role.
  3. Enter 2 to go to the Tanium Operations menu. ClosedView screen
  4. Enter 9 and follow the prompts to import and install the CAC certificate file.

Step 2: Add the required Tanium Server configuration settings

  1. Sign in to the TanOS console as a user with the tanadmin role.
  2. Enter 2 to go to the Tanium Operations menu. ClosedView screen
  3. Enter 2 to go to the Configuration Settings menu. ClosedView screen
  4. Enter 1 to go to the Tanium Server Config Settings menu. ClosedView screen
  5. Use the menu to add Tanium Server settings as described in the Enable CAC settings table.
  6. Restart the Tanium Server service. For more information, see Tanium Appliance Deployment Guide: Start, stop, and restart Tanium services.
    You can now sign in to the Tanium Console with your CAC.

The following table summarizes the settings you must add to enable CAC.

 Table 1: Enable CAC settings
Setting Names Guidelines
ForceSOAPSSLClientCert Optional. If the registry value does not exist (but other CAC/PIV registry values do exist), or is set to a value of 1, CAC/PIV authentication becomes mandatory.

Note: The design supports the value 0 to turn off client certificate authentication and use the Tanium Console sign-in credentials instead. However, the current implementation to support the value 0 is not finished. At this time, the value should only be set to 1.
ClientCertificateAuthField Optional. If it is not defined, certificate authentication matches on the Subject field.

Specify a value for this key if you want to match on a different attribute. Many organizations use X509v3 Subject Alternative Name.

Example:

X509v3 Subject Alternative Name

Note: X509v3 is typically hidden when displayed in Windows. Note that X509v3 is case sensitive.
ClientCertificateAuthRegex

Optional. If it is not defined, the default regular expression (regex) is used to match the user identifier. The default is .*CN=(.*)$.

The following expression is the best practice to match any Subject Alternative Name entry:
.*:\s(\d+)@.*
ClientCertificateAuth Defines the location of the certificate file to use for authentication, such as:

/opt/Tanium/TaniumServer/cac.pem

Note: The path name is case sensitive.

CACTrustedAddresses Defines which endpoints to exempt from CAC authentication requirements. These systems will not require a CAC/PIV certificate to authenticate and will work for all Tanium assets.

Specify the Tanium Server and Tanium Module Server. Specify additional addresses to exempt any other trusted systems and components.

In an active-active deployment, you must configure this setting on both Tanium Servers to prevent errors with TDownloader.

cac_ldap_server_url Optional. If it is defined, requires that Tanium validate every CAC/PIV authentication attempt with LDAP to determine the state of the account that is signing in. Because this does not use the Windows authentication subsystem, the service account running Tanium must have the privileges to look up accounts through a direct LDAP query.

Use the following syntax, where LDAP must be uppercase:

LDAP://<LDAP FQDN>

If multiple domains are in use, specify a global catalog in the syntax GC://<domain>.

Also configure LDAP integration in Tanium Console, and assign roles, computer groups, and personas to user groups and users that are imported from the LDAP server. See Tanium Console User Guide: Integrating with LDAP servers.
CertLDAPQueryField Optional. If it is defined, it specifies an LDAP user naming attribute. If it is not defined, the default attribute is used. Valid values are:
  • userPrincipalName — The sign in name for the user.
  • sAMAccountName — A sign in name that supports previous version of Windows.
CertLDAPCertField Optional. Add this setting in conjunction with the cac_ldap_server_url setting. This setting specifies a secondary attribute to query within the X509 certificate. Usually, this value is expected to match ClientCertificateAuthField with a value of X509v3 Subject Alternative Name.

If it is not defined, certificate authentication matches on the Subject attribute.

X509v3 is typically hidden when displayed in Windows. The string X509v3 is case sensitive.
CertLDAPCertFieldRegex Optional. Add this attribute in conjunction with the cac_ldap_server_url setting. This setting specifies a regular expression that accounts for the User Principal Name (UPN) Suffix when a secondary LDAP lookup occurs. This is necessary because LDAP synchronization matches UPN without the UPN Suffix.

If it is not defined, whatever is returned in the user naming attribute is used.

The following example is most commonly used. It returns the full UPN:

.*\:\s*([^@][email protected]*)$

The following example returns just the numeric value from the UPN:

([^@]+)@.*$

To disable CAC authentication, remove the CAC settings and then restart the Tanium Server service.

Windows: Configure CAC

Step 1: Copy the certificate to the Tanium Server installation directory

Copy the file to the Tanium Server installation directory, which by default is \Program Files\Tanium\Tanium Server.

Step 2: Add Windows registry keys on Tanium Server host

  1. Add Windows registry key entries as described in the following tables.
  2. Open the Windows Services program, right-click the Tanium Server service, and select Restart.
 Table 2: Enable smart card authentication
Location HKLM\Software\Wow6432Node\Tanium\Tanium Server
Value ForceSOAPSSLClientCert
Value Type REG_DWORD
Valid Range 0 or 1
Default Value 1
Guidelines Optional. If the registry value does not exist (but other CAC/PIV registry values do exist), or is set to a value of 1, CAC/PIV authentication becomes mandatory.

The design supports the value 0 to turn off client certificate authentication and use the Tanium Console sign in credentials instead. However, the current implementation to support the value 0 is not finished. At this time, set the value only to 1.

 Table 3: Certificate attribute to be matched
Location HKLM\Software\Wow6432Node\Tanium\Tanium Server
Value ClientCertificateAuthField
Value Type REG_SZ
Valid Range Any valid certificate field.
Default Value Subject
Guidelines Optional. If it is not defined, certificate authentication matches on the Subject field.

Specify a value for this key if you want to match on a different attribute. Many organizations use X509v3 Subject Alternative Name.

Note: X509v3 is typically hidden when displayed in Windows. Note that the string X509v3 is case sensitive.

 Table 4: Regular expression to match
Location HKLM\Software\Wow6432Node\Tanium\Tanium Server
Value ClientCertificateAuthRegex
Value Type REG_SZ
Valid Range Any valid regular expression.
Default Value .*CN=(.*)$
Guidelines

Optional. If it is not defined, the default regular expression is used to match the user's identifier.

Use the following expression to match any Subject Alternative Name entry: .*:\s(\d+\.?\w?)@.*


 Table 5: Location of the smart card certificate file
Location HKLM\Software\Wow6432Node\Tanium\Tanium Server
Value ClientCertificateAuth
Value Type REG_SZ
Valid Range Any valid certificate file.
Default Value None
Guidelines Defines the location of the certificate file to use for authentication, such as D:\Program Files\Tanium\Tanium Server\cac.pem.

The path name is case sensitive.


 Table 6: Define trusted systems and components
Location HKLM\Software\Wow6432Node\Tanium\Tanium Server
Value CACTrustedAddresses
Value Type REG_SZ
Valid Range A comma-separated list of FQDNs.
Default Value None
Guidelines Defines which endpoints to exempt from CAC authentication requirements. These systems do not require a CAC/PIV certificate to authenticate and work for all Tanium assets.

Specify the Tanium Server and Module Server. In an active-active deployment, configure this setting on both Tanium Servers to prevent TDownloader errors. Specify additional addresses to exempt any other trusted systems and components.


 Table 7: (Optional) LDAP server
Location HKLM\Software\Wow6432Node\Tanium\Tanium Server
Value cac_ldap_server_url
Value Type REG_SZ
Valid Range A valid LDAP server.
Default Value None
Guidelines Optional. If it is defined, requires that Tanium validate every CAC/PIV authentication attempt with LDAP to determine the state of the account that is signing in. Because this does not use the Windows authentication subsystem, the service account running Tanium must have the permissions to look up accounts through a direct LDAP query.

Use the following syntax, where LDAP must be uppercase: LDAP://<LDAP FQDN>

If multiple domains are in use, specify a global catalog. It must use the syntax GC://<domain>.

Also configure LDAP integration in Tanium Console, and assign roles, computer groups, and personas to user groups and users that are imported from the LDAP server. See Tanium Console User Guide: Integrating with LDAP servers.

 Table 8: (Optional) LDAP query
Location HKLM\Software\Wow6432Node\Tanium\Tanium Server
Value CertLDAPQueryField
Value Type REG_SZ
Valid Range userPrincipalName or sAMAccountName
Default Value userPrincipalName
Guidelines Optional. If it is defined, it specifies an LDAP user naming attribute. If it is not defined, the default attribute is used. The valid values are:
  • userPrincipalName — The sign in name for the user.
  • sAMAccountName — A sign in name that supports previous version of Windows.

 Table 9: (Optional) LDAP secondary lookup
Location HKLM\Software\Wow6432Node\Tanium\Tanium Server
Value CertLDAPCertField
Value Type REG_SZ
Valid Range  
Default Value Subject
Guidelines Optional. Add this setting in conjunction with the cac_ldap_server_url setting. This setting specifies a secondary attribute to query within the X509 certificate. Usually, this value is expected to match ClientCertificateAuthField with a value of X509v3 Subject Alternative Name.

If it is not defined, certificate authentication matches on the Subject attribute.

X509v3 is typically hidden when displayed in Windows. The string X509v3 is case sensitive.

 Table 10: (Optional) LDAP regex
Location HKLM\Software\Wow6432Node\Tanium\Tanium Server
Value CertLDAPCertFieldRegex
Value Type REG_SZ
Valid Range Any valid regular expression.
Default Value None
Guidelines Optional. Add this attribute in conjunction with the cac_ldap_server_url setting. This setting specifies a regular expression that accounts for the UPN Suffix when a secondary LDAP lookup occurs. This is necessary because LDAP synchronization matches UPN without the UPN Suffix.

If it is not defined, whatever is returned in the user naming attribute would be used.

The following example is most commonly used. It returns the full UPN:

.*\:\s*([^@][email protected]*)$

The following example returns just the numeric value from the UPN:

([^@]+)@.*$

Troubleshoot smart card authentication

  • Check the configuration for typos, such as extra spaces or letter case errors.
  • Test whether the system works with just the required registry keys. Then enable and test optional settings, such as the LDAP integration settings.
  • In an active-active deployment, configure the CACTrustedAddresses value with entries for each Tanium Server and the Module Server to avoid errors by the Tanium Downloader (TDownloader) service during package synchronization.
  • Set the logging level to 41 or higher on the Tanium Server and Module Server to record the following events. See Tanium Console User Guide: Configure server logging levels. If you Create a custom log that records only these events, use .*Client Certificate auth.* as the filter regex. After generating logs at level 41, search for the following log entries:

    • If ClientCertificateMatchField is set and does not match:

      • No regex match:

        Client Certificate auth logon denied, match failed

      • Field used for regex not found in the CA certificate:

        Client Certificate auth logon denied, match property not present

    • If ClientCertificateMatchField passes or is empty, the user is extracted using the ClientCertificateAuthField and ClientCertificateAuthRegex:

      • If ClientCertificateAuthRegex is not matched:

        Client Certificate auth logon denied, regex not matched

      • If ClientCertificateAuthField is not found:

        Client Certificate auth logon denied, field not found

      • If the the regex matches and the field is found but the name is not valid:

        Client Certificate auth logon denied, unknown user

    • Any other error or information message also starts with:

      Client Certificate auth