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.

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 use the Configuration > Authentication > SAML Configuration page.

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

IdP-initiated SSO

An IdP-initiated workflow has the following phases:

  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).
  2. 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).
  3. The SP uses the IdP certificate to verify that the SAML assertion 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:

  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 SAML assertion that indicates the user authenticated successfully. The user's browser automatically forwards the assertion to the SP.
  5. The SP uses the IdP certificate to verify that the SAML assertion 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 or LDAP server and managing user access through the IdP. For information about setting up an application through an IdP, refer to your IdP documentation.

    A Tanium administrator must create the Tanium Console users if they authenticate through a domain-joined Active Directory back end (see Create a user) or configure an LDAP Sync connector to import users (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

  1. Go to Configuration > Authentication > SAML and then Choose an IdP.
  2. 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.

  3. 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.
  4. (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.
  5. 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 (clear 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.
  7. 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.
  8. Save your changes. The Tanium Server SAML SP service then starts.

    Next, be sure to Turn off the password prompt for configuration changes.

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

Turn off the password prompt for configuration changes

An important benefit of SSO is that it minimizes the number of times that users must respond to a password prompt when accessing and using applications. If you previously configured the Tanium Server to display a password prompt whenever users make a configuration change, you can optionally change it to a Yes/Cancel prompt to simplify the user experience.

  1. Go to Configuration > Miscellaneous > Confirmation Prompt.
  2. Select Show a Yes/Cancel prompt.
  3. Save your changes.

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 hostnames 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 filenames.

    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 Guide for Windows: Tanium Server CLI).
  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. Go to Configuration > Authentication > SAML.
  2. Set Choose an IdP to No Provider and save your changes.

Last updated: 7/30/2019 3:04 PM | Feedback