Smart card authentication

Tanium as a Service 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.

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 one of the following sources:

  • 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. The following are some examples:

  • 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
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 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 Console 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 file name. 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 preceding example shows the root certificate last, which is a convention that Tanium Support uses.

  3. Save the file.

Tanium Appliance: Configure CAC

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

Step 1: Install the certificate

Upload and then 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 Table 1.
  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 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 is used to match the user's identifier. The default is .*CN=(.*)$.

The following example 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.

Example:

/opt/Tanium/TaniumServer/cac.pem

Note: The path name is case sensitive.

TrustedHostList 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.
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 AD to determine the state of the account that is signing 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.

CertLDAPQueryField 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.
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. 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.

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

([^@]+)@.*$

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 installation directory

Copy the file to the Tanium Server installation directory:

\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. Restart the Tanium Server service.
 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.

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


 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.

Example:

X509v3 Subject Alternative Name

Note: X509v3 is typically hidden when displayed in Windows. Note that 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.

The following example is the best practice 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.

Example:

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

Note: The path name is case sensitive.


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


 Table 8: (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 signing in. This does not use the Windows authentication subsystem, so the service account running Tanium must have the permissions 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 9: (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 sign in name for the user.
  • sAMAccountName — A sign in name that supports previous version of Windows.

 Table 10: (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 11: (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 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 Tanium Module Server to avoid TDownloader errors during package synchronization.
  • Set the logging level to 41 or higher to log the following events:
    • 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