Integrating with a SAML IdP

Tanium as a Service is preconfigured to integrate with your Security Assertion Markup Language (SAML) identity provider (IdP).

SAML overview

Security Assertion Markup Language (SAML) is a standard for exchanging authentication requests and responses between service providers (SPs) and identity providers (IdPs). It enables SPs to give users access to applications across multiple security domains through a single sign-on (SSO) authentication service that the IdP provides. Upon receiving an authentication request, the IdP responds with a SAML assertion, which is a message that indicates whether a user authenticated successfully. In the context of the Tanium Core Platform, enabling SAML means configuring the Tanium Server as an SP to give users access to the Tanium Console. You can configure the following types of SAML SSO authentication for console access:

  • Tanium Server 7.2.314.3181 and later integrates with Okta as an IdP, and supports IdP-initiated SSO.
  • Tanium Server 7.2.314.3476 and later integrates with any IdP, and supports both IdP-initiated and SP-initiated SSO.

After signing into the IdP, a user can start new Tanium Console sessions repeatedly without re-authenticating, until the IdP session times out. The IdP session timeout is configured on the IdP server; consult your IdP administrator for more information.

You can configure the Tanium Server to support both IdP-initiated and SP-initiated SSO or only IdP-initiated SSO. You cannot configure only SP-initiated SSO.

Maintain at least one user account on the Tanium Server that does not require SAML authentication and assign that account the Administrator reserved role. You can use this account to access the Tanium Console if SAML authentication stops working (for example, if the connection to the IdP goes down).

The Tanium Server does not support user authorization (role-based access control) through SAML. To control the features, settings, and information that users are allowed to see and use after accessing the Tanium Console, configure user role permissions. For details, see RBAC overview.

Only users who have the Administrator reserved role can see and manage the SAML configuration.

IdP-initiated SSO

In some enterprises, users are expected to access many or all applications by signing into a single SSO portal that the enterprise IdP provides. After you enable SAML on the Tanium Server, users can access the Tanium Console through the IdP SSO portal. An IdP-initiated workflow has the following phases (matching the numbers in Figure  1):

A1 A user signs into the IdP SSO portal using an enterprise username and password, and clicks an application tile (the Tanium Console tile, in this example).

2 The IdP returns a signed response (which contains a SAML assertion) that indicates the user authenticated successfully. The user's browser automatically forwards the response to the SP (the Tanium Server in this example).

3 The SP uses the IdP certificate to verify that the SAML response signature is valid.

4 The SP provides the user access to the application.
Figure  1:  IdP-initiated SAML SSO

SP-initiated SSO

An SP-initiated workflow has the following phases (matching the numbers in Figure  2):

1 The user tries to access the application (the Tanium Console in this example) directly through the SP (the Tanium Server in this example).

2 The SP redirects the user to authenticate through the IdP. The user's browser processes the redirection automatically.

3 The user logs into the IdP.

4 The IdP returns a signed response (which contains a SAML assertion) that indicates the user authenticated successfully. The user's browser automatically forwards the response to the SP.

5 The SP uses the IdP certificate to verify that the SAML response signature is valid.

6 The SP provides the user access to the application.
Figure  2:  SP-initiated SAML SSO

Before you begin

  • Work with the IdP administrator to identify which users must access the Tanium Console through the IdP. The IdP administrator is responsible for configuring authentication through an Active Directory (AD) or Lightweight Directory Access Protocol (LDAP) server and managing user access through the IdP. For information about setting up an application through an IdP, refer to your IdP documentation.

    An administrator must create the Tanium Console users if they are local to the Tanium Server (see Create a user) or must import the users from an LDAP server (see Integrating with LDAP servers).

  • (Optional) Obtain an IdP metadata file from the IdP administrator. This XML file specifies IdP-specific settings that enable the Tanium Server to trust the IdP. For example, the file specifies the entity ID, also known as the audience Uniform Resource Identifier (URI), which is the globally unique identifier for the IdP in SAML communications. Usually and ideally, the metadata file also includes the IdP certificate, which the Tanium Server must use to validate SAML responses and assertions from the IdP. Otherwise, you must obtain the certificate from the IdP administrator separately from the metadata file. The certificate file must be Privacy Enhanced Mail (PEM)-encoded.
  • Generate a certificate for signing authentication requests from the Tanium Server. Some IdPs require signed requests. See Generate a request-signing certificate.
  • (IdP-initiated SSO only) If changes occur to the URLs where Tanium Console users access the IdP SSO portal, work with the IdP administrator when rolling out the changes.

Generate a request-signing certificate

Some IdPs require a digital signature on SAML requests from an SP such as the Tanium Server. To enable the IdP to authenticate requests, you must generate a request-signing certificate and private key. The Tanium Server uses the key to sign the requests and the IdP uses the certificate to validate the signature.

Generate a request-signing certificate in a Tanium Appliance deployment

Contact Tanium Support for the steps to generate a request-signing certificate in a Tanium Appliance deployment.

Generate a request-signing certificate in a Windows deployment

After generating the SAML request-signing certificate, you must restart the Tanium Server for it to read the certificate. Therefore, perform the following steps during a period when restarting the server will not interrupt critical operations.

  1. Access the Tanium Server CLI. If necessary, elevate permissions to open the command prompt as the administrator user.


  2. Go to the Tanium Server installation folder.
  3. Run the following command to generate the certificate and private key. For the <hostname>, specify the FQDN of the Tanium Server. In an active-active deployment, separate the host names with a comma (such as ts1.example.com,ts2.example.com). You must specify SAMLEncryption as the certificate and key file names for the server to use them for SAML communication. The utility automatically appends the .crt and .key suffixes to the certificate and key file names.

    KeyUtility selfsign <hostname> SAMLEncryption

    The utility generates the certificate and key at the top level of the Tanium Server installation folder.

  4. Open the Windows Services program and restart the Tanium Server service.

    As long as the certificate and key files remain in the top level of the Tanium Server installation folder, the server automatically uses the key to sign SAML requests and includes the certificate in the Tanium Metadata file that you send to the IdP (see Configure SAML authentication).

    Alternatively, you can add the SAMLEncryptionCertPath and SAMLEncryptionKeyPath settings on the Tanium Server to configure different file names and locations for the certificate and key. Contact Tanium Support for details.

Configure SAML authentication

Perform the following steps to configure SP-initiated or IdP-initiated SAML SSO.

If you previously enabled a password prompt for configuration changes, the Tanium Server automatically changes it to a Yes/Cancel prompt after you enable SAML authentication.
  1. From the Main menu, go to Administration > Configuration > SAML Configuration and click one of the following buttons:
    • Configure SAML: This button appears if no IdP is currently configured.
    • Edit Edit: Click this button to edit the existing configuration.

      Specifying a new IdP removes any existing IdP configuration because the Tanium Server supports only one IdP at a time.

  2. Configure the following fields:
     Table 1: SAML configuration settings
    SettingsGuidelines
    Identity Provider MetadataIf your IdP administrator provided an IdP metadata file, upload it to automatically configure the following SAML settings:
    • Entity ID Configuration: The Validate IdP's Entity ID setting is selected by default and the text field contains the IdP entity ID.
    • Identity Provider Certificate: The metadata usually contains the certificate. If not, you must manually upload the certificate file.
    • Identity Provider SSO URL: If the metadata specifies this URL, the Enable SP-initiated SSO option is automatically selected.

    To upload the IdP metadata file, click Choose File, select the file, and click Open.

    Entity ID ConfigurationBy default, Validate IdP's Entity ID is selected: the Tanium Server validates the entity ID in SAML responses from the IdP. The text field displays the ID from the Identity Provider Metadata file that you imported (for example, http://www.okta.com/gzn4gvh7dvpeDr6oG4g1).

    Enabling Validate IdP's Entity ID is optional but a security best practice to provide another layer of protection in addition to using the IdP certificate to validate SAML responses.

    Elements which must be signedBy default, every SAML Response and SAML Assertion from the IdP require a digital signature, which the Tanium Server validates using the IdP certificate. Optionally, you can disable the signature requirement for SAML assertions but not responses.
    Identity Provider CertificateThe Tanium Server uses the IdP certificate to validate SAML responses and assertions from the IdP. If the Identity Provider Metadata specifies the certificate, the Tanium Server automatically extracts it and populates this setting with the certificate file name. Otherwise, you must manually upload the certificate that the IdP provided separately from the metadata: click Update File, select the certificate, and click Open.
    Tanium Entity IDThe entity ID of your Tanium environment. The Tanium Server automatically generates an ID, but you can replace it with any Uniform Resource Identifier (URI) that uniquely identifies your Tanium environment in SAML communications. The URI is typically a URL that contains the Tanium Server domain name (such as https://tanium.example.com/sp).
    Customize Tanium ACS URLsSelect this option if the Assertion Consumer Service (ACS) URL that the Tanium Server generates by default will not work in your deployment. The server uses the ACS URL to receive and process SAML assertions from the IdP. The default URL is based on the actual host name or IP address of the server, which might differ from the host name or address that users specify in their browser to access the Tanium Console. Select an option:
    • Use the same host name for all Tanium Servers: Select this option if your deployment uses a load balancer that masks the presence of one or more Tanium Servers. For the Shared Custom Hostname, enter the host name or IP address that users specify in their browser to access the Tanium Console.
    • Specify unique host names for each Tanium Server: Select this option if users access the Tanium Console of each active-active Tanium Server using separate host names or IP addresses. Enter the Custom Host Name of each server.

      In rare circumstances, one of the Tanium Servers in an active-active deployment might not be registered yet. In such cases, enter the Custom Host Name of each server anyway to ensure that both can function as an SP when the unregistered server does register.

    SP-Initiated SSO ConfigurationIf the Identity Provider Metadata specifies an Identity Provider SSO URL, the Tanium Server automatically populates this setting and selects Enable SP-initiated SSO. This is the URL where users access the Tanium Console (for example, https://company.saml-provider.com/app/companyinc_tanium/dGFuaXVtc2FtbA/sso/saml). If you want users to access the console only through the IdP SSO portal, deselect Enable SP-initiated SSO.

    Select the sign-in options if you enable SP-initiated SSO:

    • Allow users to sign in with username and password: This setting controls whether the Tanium Console sign-in page displays a Sign In with Password link.Sign-in page

      This link gives users the option to access the Tanium Console by entering credentials instead of using SSO. Deselect this option if you want to force all users to authenticate through SAML SSO when they sign in to the console. The option applies only to console access and does not control access to the Tanium Server CLI or API through any authentication method.

      If you disable password sign ins and SP-initiated SSO later stops working (for example, the connection to the IdP goes down), no users can access the Tanium Console. In such cases, you must disable SP-initiated SSO through the CLI to re-enable local or LDAP password authentication: see Disable SP-initiated SSO through the CLI.

      To disable LDAP password-based authentication at the API level, disable the Authentication option in the LDAP server configuration.

    • Force full user re-authentication at every sign-in: Select this option if you want to force users to enter sign-in credentials when they start a new Tanium Console session even if they already authenticated for a previous session that ended due to inactivity or a manual sign-out event. By default, this option is deselected and users can just click Sign In with SSO to start another Tanium Console session without entering sign-in credentials.
  3. Click Save.

    You must wait up to three minutes for the Tanium Server to apply your changes. If you changed the SP-Initiated SSO Configuration settings for an existing SAML configuration, you must also manually refresh the sign-in page after waiting.

    If the Tanium Metadata section displays the message Request Signing Certificate Not Configured, consider generating the certificate before proceeding. See Generate a request-signing certificate.

  4. If the IdP supports metadata exchange documents, click Download in the Tanium Metadata section to export the metadata file to the Downloads directory on the system that you use to access the Tanium Console. The Tanium Server automatically generates the metadata based on the settings that you configured in the SAML Configuration page. You must send the file to the IdP. The IdP administrator then uses the file to configure the IdP with the settings that are required to communicate with the Tanium Server. If the IdP does not support metadata exchange documents, the IdP administrator must manually configure the settings in the IdP system. After the administrator configures the IdP system, users can start accessing the Tanium Console through SSO.

For the steps to sign in to the Tanium Console through SSO, see Sign in to the Console.

Disable or Enable SAML SSO

Initially, you enable SAML SSO by performing the steps under Configure SAML authentication. If disabling SSO becomes necessary, such as for troubleshooting authentication issues, you can later re-enable it. While SSO is disabled, users must enter their username and password to sign in to the Tanium Console.

If SSO stops working (for example, the connection to the IdP goes down), users can access the console through sign-in credentials only if you selected Allow users to sign in with username and password in the SAML configuration. If you deselected that option, you must Disable SP-initiated SSO through the CLI to re-enable access through sign-in credentials.

Disable SSO through the Tanium Console

  1. From the Main menu, go to Administration > Configuration > SAML Configuration.
  2. Click Disable SAML.

Enable SSO through the Tanium Console

  1. From the Main menu, go to Administration > Configuration > SAML Configuration.
  2. Click Enable SAML.
  3. (Optional) Select Enable SP-initiated SSO and edit the SP-Initiated SSO Configuration options if necessary.
  4. Click Save.

Disable SP-initiated SSO through the CLI

If you ever need to disable SP-initiated SSO without accessing the Tanium Console, you can set the global setting console_saml_sp_enabled through the CLI.

Disable SSO in a Tanium Appliance deployment

Contact Tanium Support for the steps to disable SSO in a Tanium Appliance deployment.

Disable SSO in a Windows deployment

  1. Access the Tanium Server CLI. If necessary, elevate permissions to open the command prompt as the administrator user.


  2. Go to the Tanium Server installation folder.
  3. Run the following command:

    TaniumReceiver global-settings set console_saml_sp_enabled 0

    Wait up to a minute for the change to apply, or restart the Tanium Server service to apply the change immediately. You can find the Tanium Server service in the Windows Services program.