Integrating with a SAML IdP

Use the Tanium Cloud Management Portal (CMP) to:

Configure your Security Assertion Markup Language (SAML) identity provider (IdP).
Manage your existing IdP configurations.
Configure System for Cross-Domain Identity Management (SCIM) to automatically provision IDP users and groups into Tanium.
View your Tanium instance and entitlement details.

For details, see Tanium Cloud Deployment Guide: Configuring identity providers and user provisioning in the CMP.

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 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, assign user groups, roles, personas, and computer groups to the users. For details, see Managing users.

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

If a user cannot sign in to the Tanium Console through SAML, verify that the user account is not renamed, deleted, disabled, or locked out in the IdP identity store. To troubleshoot other issues with your SAML integration, review the authentication log. To find specific events, open the log in a text editor or use CLI commands to search for keywords such as SAML. See Tanium Core Platform Deployment Reference Guide: Authentication logs.

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

	A user signs into the IdP SSO portal using an enterprise user name and password, and clicks an application tile (the Tanium Console tile in this case).
	The IdP returns a signed response (which contains a SAML assertion) that indicates the user authenticated successfully. The user browser automatically forwards the response to the SP (the Tanium Server in this case).
	The SP uses the IdP certificate to verify that the SAML response signature is valid.
	The SP provides the user access to the application.

Figure 1: IdP-initiated SAML SSO (click image to enlarge)

SP-initiated SSO

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

	The user tries to access the application (the Tanium Console in this case) directly through the SP (the Tanium Server in this case).
	The SP redirects the user to authenticate through the IdP. The user browser processes the redirection automatically.
	The user signs in to the IdP.
	The IdP returns a signed response (which contains a SAML assertion) that indicates the user authenticated successfully. The user browser automatically forwards the response to the SP.
	The SP uses the IdP certificate to verify that the SAML response signature is valid.
	The SP provides the user access to the application.

Figure 2: SP-initiated SAML SSO (click image to enlarge)

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.

Access the Tanium Server CLI. If necessary, elevate permissions to open the command prompt as the administrator user.
Go to the Tanium Server installation folder.
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.
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 Integrating with a SAML IdP).
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 on the Tanium Server

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.

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

Configure the following fields:

Table 1: SAML configuration settings
Settings	Guidelines
Identity Provider Metadata	If 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 Configuration	By default, Validate IdP's Entity ID is selected, which means that 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 signed	By default, every SAML Response and SAML Assertion from the IdP requires a digital signature, which the Tanium Server validates using the IdP certificate. If your IdP is Microsoft Azure, both the response and assertion require a signature. For other IdPs, you can disable the signature requirement for SAML assertions but not responses.
Identity Provider Certificate	The 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 ID	The 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 URLs	Select 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. This option is required if your IdP supports only one ACS URL for each SP. 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 Configuration	If 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. 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.

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.
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. See Configure SAML on the IdP.

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

Configure SAML on the IdP

Work with an IdP administrator to configure the IdP for integration with the Tanium Server.

Before you begin

Perform one of the following tasks based on whether the IdP supports metadata exchange documents:

Supported: Import the Tanium metadata file into the IdP to automatically configure settings that you already configured on the Tanium Server, as described in the last step of Configure SAML on the Tanium Server.
Not supported: Record the settings that you must manually enter in the IdP:
1. Sign in to the Tanium Console as a user with the Administrator role.
2. From the Main menu, go to Administration > Configuration > SAML Configuration.
3. Record the Tanium Entity ID and Tanium ACS URLs values and provide them to the administrator who will configure the IdP for integration with the Tanium Server.

Configure Tanium Server settings on the IdP

The specific steps to configure an IdP for integration with an SP (the Tanium Server in this case) vary by IdP vendor. However, all IdPs require the following settings. If you imported the Tanium metadata file, settings from that file are automatically configured in the IdP and you just have to verify them.

Tanium Entity ID
Tanium ACS URLs
NameID format: Set to Unspecified. In SAML assertions, the NameID value must match the User Name (not the Display Name) of a user on the Tanium Server (see View user settings). If the server imports users through LDAP, the NameID value must match the User Name Property value for each user.
RelayState: Set to no value (blank). The Tanium Server does not process this setting.

After the administrator configures the IdP, users can start accessing the Tanium Console through SSO.

Disable or enable SAML SSO

Initially, you enable SAML SSO by performing the steps under Integrating with a SAML IdP. 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

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

Enable SSO through the Tanium Console

From the Main menu, go to Administration > Configuration > SAML Configuration.
Click Enable SAML.
(Optional) Select Enable SP-initiated SSO and edit the SP-Initiated SSO Configuration options if necessary.
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. The steps to disable SP-initiated SSO depend on whether your Tanium deployment uses Tanium Appliance or Windows infrastructure.

Appliance: Disable SSO

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

Windows: Disable SSO

Access the Tanium Server CLI. If necessary, elevate permissions to open the command prompt as the administrator user.
Go to the Tanium Server installation folder.
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.