Integrating with a SAML 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 logging 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.

As a best practice, 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).

IdP-initiated SSO

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 username and password, and clicks an application tile (the Tanium Console tile, in this example).
	The IdP generates a signed SAML assertion that indicates the user authenticated successfully. The user's browser automatically forwards the assertion to the SP (the Tanium Server in this example).
	The SP uses the IdP certificate to verify that the SAML assertion signature is valid.
	The SP provides the user access to the application.

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 example) directly through the SP (the Tanium Server in this example).
	The SP redirects the user to authenticate through the IdP. The user's browser processes the redirection automatically.
	The user logs into the IdP.
	The IdP returns a signed SAML assertion that indicates the user authenticated successfully. The user's browser automatically forwards the assertion to the SP.
	The SP uses the IdP certificate to verify that the SAML assertion signature is valid.
	The SP provides the user access to the application.

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

• Work with the IdP administrator when rolling out changes in the URLs where Tanium Console users access the IdP SSO portal (IdP-initiated SSO only).

Configure SAML authentication

Perform the following steps to enable 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, select Administration > Configuration > Authentication and click SAML.
2. Select an IdP from the Choose an IdP drop-down.
3. In the Tanium URIs for <IdP> Configuration section, copy the Single sign on URL and Audience URI (SP entity ID) values and share them with the IdP administrator. The administrator needs this information to configure the IdP to support the Tanium Console application.

   Before you perform the remaining steps, the IdP administrator must send you the IdP certificate that the Tanium Server will use to validate SAML messages received from the IdP service.

4. In the <IdP> Configuration Information section, use the controls to upload the IdP certificate file. Later in this procedure, after you save all your configuration changes, this section displays the certificate name as a link, which you can click to open a popup containing the certificate contents.
5. (Custom IdP only) Configure the following settings in the Custom IdP Settings section. All the settings are required except where otherwise noted. These settings refer to elements, attributes, and values in the XML-based SAML response messages that the IdP sends to the Tanium Server after users attempt to authenticate.

Table 1:   Custom IdP settings

Settings	Guidelines
Name	Name that identifies the IdP.
xp_response_destination	Xpath selector for the response destination within the Response element. For example: @Destination. The destination is the URL to which the IdP sends the SAML response. The Tanium Server uses the sec_response_allowed_destination setting to validate the destination.
xp_response_issuer	Xpath selector for the response issuer identifier within the Response element. For example: Issuer/text(). The Tanium Server uses the sec_response_allowed_issuer setting to validate the issuer identifier.
xp_response_status	Xpath selector for the response status code within the Response element. For example: Status/StatusCode/@Value. The status code indicates whether authentication succeeded at the IdP.
xp_response_id	Xpath selector for the response identifier within the Response element. For example: @ID. The Tanium Server uses the identifier to ensure the response signature refers to the correct element.
xp_response_issue_instant	Xpath selector for the response issue time within the Response element. For example: @IssueInstant. The Tanium Server uses the issue instant to ensure the response did not expire.
xp_assertion_issuer	Xpath selector for the assertion issuer identifier within the Assertion element. For example: Issuer/text(). The Tanium Server uses the sec_assertion_allowed_issuer setting to validate the issuer identifier.
xp_assertion_audience	Xpath selector for the expected assertion audience within the Assertion element. For example: Conditions/AudienceRestriction/Audience/text(). The Tanium Server uses the sec_assertion_allowed_audience setting to validate the expected audience.
xp_assertion_username	Xpath selector for the username within the Assertion element. For example: Subject/NameID/text(). The Tanium Server uses the setting to retrieve the username of the user who tried to authenticate.
xp_assertion_recipient	Xpath selector for the recipient value within the Assertion element. For example: Subject/SubjectConfirmation/SubjectConfirmationData/@Recipient. The recipient is where the IdP sends the SAML assertion. The Tanium Server uses the sec_assertion_allowed_recipient setting to validate the recipient.
xp_assertion_auth_class	Xpath selector for the authentication class within the Assertion element. For example: AuthnStatement/AuthnContext/AuthnContextClassRef/text(). The authentication class represents the method that the IdP used to authenticate the user. The Tanium Server uses the sec_assertion_allowed_auth_context_classes setting to validate the authentication class.
xp_assertion_cond_before	Xpath selector for the not-before condition within the Assertion element. For example: Conditions/@NotBefore. The not-before condition indicates the date and time before which the assertion is not valid. If you set sec_check_assertion_time_constraints to true, xp_assertion_cond_before requires a value.
xp_assertion_cond_after	Xpath selector for the not-on-or-after condition within the Assertion element. For example: Conditions/@NotOnOrAfter. The not-on-or-after condition indicates the date and time when the assertion becomes invalid. If you set sec_check_assertion_time_constraints to true, xp_assertion_cond_after requires a value.
sec_check_assertion_time_constraints	Optional setting that enables (select the check box) or disables (deselect the check box) validation of the not-before (xp_assertion_cond_before) and not-on-or-after (xp_assertion_cond_after) date and time conditions for the assertion.
sec_assertion_allowed_auth_context_classes	Optional comma-separated list of possible values for the authentication class that represents the method that the IdP used to authenticate the user. For example: urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport.
sec_assertion_allowed_issuer	Optional validation value for the assertion issuer identifier. For example: http://www.saml-provider.com/YWJjZGVmMTIzNA.
sec_assertion_allowed_recipient	Optional validation value for the assertion recipient URL. For example: https://myhost.company.com/saml2/auth/custom.
sec_assertion_allowed_audience	Optional expected value for the assertion audience. For example: tanium-saml2.
sec_elt_assertion_signed	Select this option if you want the Tanium Server to verify the signature of the assertion from the IdP.
sec_response_allowed_issuer	Optional validation value for the response issuer identifier. For example: http://www.saml-provider.com/YWJjZGVmMTIzNA.
sec_response_allowed_destination	Optional validation value for the response destination URL. For example: https://myhost.company.com/saml2/auth/custom.
sec_response_expiration	Optional time period in seconds when a response is valid and reusable. If you do not specify a value, the default period is 300 seconds (five minutes).

6. (SP-initiated SSO only) In the Service Provider Initiated SSO section, select Enable SP-initiated SSO and configure the following required fields.

Table 2:   SP-initiated SSO settings

Settings	Guidelines
idp_sso_service_url	SSO URL where users access the service through the IdP. For example: https://company.saml-provider.com/app/companyinc_tanium/dGFuaXVtc2FtbA/sso/saml.
idp_sso_issuer	Expected issuer identifier for the SAML response. For example: http://www.saml-provider.com/YWJjZGVmMTIzNA. The value must match the sec_assertion_allowed_issuer and sec_response_allowed_issuer values.
idp_sso_force_reauth	Select enabled if you want to force users to enter login 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 logout event. By default, this option is disabled and users can just click Login with SSO to start another Tanium Console session without entering login credentials.
Disable password login for Tanium Console	Select this option if you want to force all users to authenticate through SAML SSO when they log into the Tanium Console. The option applies only to Tanium Console access and does not prevent access to the Tanium Server CLI or API through any authentication method. You must wait up to three minutes for your selection to apply. Alternatively, restart the Tanium Server service to apply the change immediately: see Manage the Tanium Server service. After the change takes effect, the login page no longer displays a Login with password option. If you disable password logins and SAML authentication 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: see Configure an LDAP server.

7. Save your changes. The Tanium Server SAML SP service then starts.

   For the steps to log into the Tanium Console through SAML SSO, see Log in using SAML SSO authentication.

Secure SAML communication

Optionally, you can improve the security of SAML communications by digitally signing authentication requests from the Tanium Server and encrypting responses (assertions) from the IdP. The Tanium Server installation includes a utility for generating an RSA private key to sign the requests and a self-signed certificate to encrypt the responses. The certificate uses the AES-256-CBC cipher for encryption.

1. Access the Tanium Server CLI and change directory (cd command) to the Tanium Server installation directory (such as D:\Program Files\Tanium\Tanium Server).
2. Run the following command to create the certificate and private key. For the <hostname>, specify the FQDN of the Tanium Server. In a high availability (HA) deployment, separate the host names with a comma (such as ts1.example.com,ts2.example.com). For the output (<out>), specify the certificate and key name (such as SAMLEncryption). The utility automatically appends the .crt and .key suffixes to the certificate and key file names.

   KeyUtility selfsign <hostname> <out>

   The utility creates the certificate and key (such as SAMLEncryption.cert and SAMLEncryption.key) at the top level of the Tanium Server installation directory. As long as you keep the certificate and key there, the Tanium Server will automatically use the certificate to sign SAML authentication requests and use the private key to decrypt IdP responses.

   Alternatively, you can add the SAMLEncryptionCertPath and SAMLEncryptionKeyPath settings on the Tanium Server to configure a different location for storing the certificate and key. For details, consult your Technical Account Manager (TAM).

3. Provide the certificate to the IdP. Work with your IdP administrator to configure the IdP to use the certificate for encrypting SAML responses, using RSA-OAEP-MGF1P (recommended) or RSA version 1.5 for secure key transportation.

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.

1. Access the Tanium Server CLI (for details, see Tanium Core Platform Deployment Reference Guide: Command-line interface).
2. Go to the Tanium Server installation directory.
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 to apply the change immediately.

Turn off the Tanium Server SAML SP service

If you ever need to stop the Tanium Server from functioning as a SAML SP, you can stop the SP service by removing the IdP settings.

1. From the Main menu, select Administration > Configuration > Authentication and click SAML.
2. Set Choose an IdP to No Provider and save your changes.