Other versions

Reference: 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.

Deployment 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:

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

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

  • SSRS plugin
  • Excel plugin (unless using the version that supports smart card authentication)
  • Connection Manager – AD Sync
  • Pytan
  • 3rd party SOC websites that query Tanium for data
There are additional caveats for an air gap deployment with smart card authentication:
  • 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 solution module imports use both the local loopback address (for the workbench) and the Tanium Module Server FQDN for the portion of the solution installed on the Tanium Module Server.

Create a certificate

Smart card authentication for Tanium access depends on the public key infrastructure (PKI) that has been set up for the enterprise. You can get started if you have a client certificate that has been signed by the root certificate for the domain in which the Tanium Server is deployed. Make sure it has the Proves your identity to a remote computer attribute.

Figure  1:  Proves your identity to a remote computer

The following procedure shows how to extract certificates from the client certificate and use them to create a new certificate file.

In most cases, you only need to extract the root certificate. If this does not work, you might need to add intermediate certificates to the chain as well.

Extract the certificates

  1. Get a copy of a client certificate file that has been signed by the root CA for the domain. See Figure  1.
  2. On a Windows computer, 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 filename. Name it something like example1.cer.
  7. Review the settings and click Finish to save the certificate.
  8. If your deployment has intermediate CAs, repeat these steps to extract the certificates for any intermediate CAs. 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 like 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 example above shows the root certificate last. Placing the root certificate last is a convention used and recommended by Tanium TAMs.
  3. Save the file.

Copy to the Tanium installation directory

Copy the file to the Tanium Server installation directory:

\Program Files\Tanium\Tanium Server\

Add Windows registry keys on Tanium Server host

  1. Add Windows registry key entries as described in the following tables.
  2. Restart the Tanium Server service.
Table 1:   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.

Note: The design supports the value 0 to turn off client certificate authentication and use the console login 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.

 

Table 2:   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.

Example:

X509v3 Subject Alternative Name

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

 

Table 3:   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.

The following example is recommended to match any Subject Alternative Name entry:

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

 

Table 4:   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.

Example:

D:\Program Files\Tanium\Tanium Server\cac.pem

Note: The pathname is case sensitive.

 

Table 5:   Add 127.0.0.1 and [::1] to the TrustedHostList entry
Location HKLM\Software\Wow6432Node\Tanium\Tanium Server
Value TrustedHostList
Value Type REG_SZ
Valid Range A comma-separated list of IP addresses or FQDNs for the Tanium Server, Module Server, and database server host computers. You must enter IPv6 addresses within square brackets (for example, [2001:db8::1]).
Default Value None
Guidelines Do not remove any values. Instead, append 127.0.0.1 (for IPv4) and [::1] (for IPv6) so that TDownloader can add local packages to the Tanium Server with CAC/PIV enabled.

 

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 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 HA deployment, you must configure this setting on both Tanium Servers to prevent errors with TDownloader.

 

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 AD to determine the state of the account that is logging in. This does not use the Windows authentication subsystem, so the service account running Tanium must have the privileges to look up accounts via direct LDAP query.

Use the following syntax:

LDAP://<Active Directory FQDN>

Note: LDAP must be in uppercase characters.

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

Tip: It is highly recommended that you also use Tanium Connection Manager to align AD users and security groups with roles in Tanium.

 

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 Active Directory user naming attribute. If it is not defined, the default attribute is used. Valid values are:
  • userPrincipalName — The logon name for the user.
  • sAMAccountName — A logon 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. Most of the time, this value should match ClientCertificateAuthField with a value of X509v3 Subject Alternative Name.

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

Example:

X509v3 Subject Alternative Name

Note: 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 AD-Sync matches UPN without the UPN Suffix.

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

Examples:

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

  • Check the registry key entries for typos (i.e. extra space).
  • Test whether the system works with just the required registry keys. Then, enable and test optional settings, such as the LDAP integration settings.
  • In HA deployments, the CACTrustedAddresses value must be configured with entries for each Tanium Server and the Tanium Module Server in order to avoid TDownloader errors during package synchronization.
  • Set log level 81 or 91 to log the following events:
    • No regex match:

      Client Certificate auth logon denied, match failed: " + authRequest.GetClientCertificateMatchRegex() + " does not match " + (*iter).second

    • Field used for regex not found in the CA:

      Client Certificate auth logon denied, match property not present. Property: " + authRequest.GetClientCertificateMatchField()

    • If it does match but the name is not valid, we log:

      Client Certificate auth logon denied, unknown user: ") + userName

    • If it does not match:

      Unable to extract certificate user, no match

Last updated: 10/22/2018 1:51 PM | Feedback