Other versions

Using 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 security domains through a single sign-on (SSO) authentication service that the IdP provides. You can configure the Tanium Server as an SP to give users access to the Tanium Console through the following types of SAML SSO authentication.

  • Tanium Server 7.2.314.3181 and later integrates with Okta as an IdP and supports IdP-initiated SSO. Users initiate the workflow by signing into the Okta SSO portal using their enterprise username and password. Okta then exchanges authentication messages with the SP and, if authentication succeeds, the user can then click the application tile of the application they want to access.
  • Tanium Server 7.2.314.3476 and later integrates with any IdP, and supports both IdP-initiated and SP-initiated SSO. In an SP-initiated workflow, users try to access the application directly, at which point the SP redirects them to sign into the IdP first. The IdP then exchanges authentication messages with the SP and, if authentication succeeds, the user can then access the application.

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.

User role requirements

Only users assigned the Administrator reserved role can see and use the Configuration pages, including the SAML configuration page.

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

  • 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.
    elt_response Name of the Response element. This is usually the top node, specified by a period "." character.
    elt_response_sig Name of the Signature element within the Response element. For example: Signature.
    elt_assertion Name of the Assertion element within the Response element. For example: Assertion.
    elt_assertion_sig Name of the Signature element within the Assertion element. For example: Signature.
    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.
    xp_signature_info Xpath selector for the signed information within a Signature element. For example: SignedInfo. The information contains the metadata of the referenced element.
    xp_siginfo_reference Xpath selector for the signature reference within the SignedInfo element. For example: Reference. The reference contains information about the signed element.
    xp_reference_uri Xpath selector for the reference URI within the Reference element. For example: @URI. The Tanium Server compares the URI to the ID of the signed element to ensure that it performs signature validation for the correct element.
    xp_reference_digest_method Xpath selector for the reference digest method within the Reference element. For example: DigestMethod/@Algorithm. The digest method indicates the algorithm used to create the digest.
    xp_reference_digest_value Xpath selector for the reference digest value within the Reference element. For example: DigestValue/text(). The digest value is the hash of the referenced element, computed using a specific algorithm. The Tanium Server uses the digest value to validate the digest that is computed at runtime for the referenced element. Any difference between the two values indicates tampering with the referenced element.
    xp_siginfo_signature_method Xpath selector for the signature method within the SignedInfo element. For example: SignatureMethod/@Algorithm. The signature method indicates the algorithm used to create the signature.
    xp_signature_value Xpath selector for the signature value within the Signature element. For example: SignatureValue/text(). The value is the signature of the signed information, computed using a specific algorithm. The Tanium Server uses the IdP certificate uploaded to the Tanium Console (in the Custom Configuration Information section) to validate the signature. Failed signature verification indicates tampering with the signed information.
    xp_signature_certificate Optional Xpath selector for the signature certificate within the SignedInfo element. For example: KeyInfo/X509Data/X509Certificate/text(). The Tanium Server uses the xp_signature_certificate to retrieve the certificate from the SAML response, and compares it to the IdP certificate uploaded to the Tanium Console (in the Custom Configuration Information section). If the certificates differ, the SAML response is considered invalid
    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_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.

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: 2/6/2019 2:40 PM | Feedback