Reference: Encryption management recovery portal

The recovery portal is not supported in Tanium Cloud.

The recovery portal is an optional self-service website that users can access if they forget their PIN or password. This website is typically Internet-facing in a DMZ so that users who forget their PIN or password can access it from another device.

Do not host this website on the same machine as the database that is used to store the recovery keys.

Requirements

Supported operating systems

  • CentOS 6
  • CentOS 7
  • CentOS 8
  • RHEL 6
  • RHEL 7
  • RHEL 8
  • Oracle Linux 6 (OEL6)
  • Oracle Linux 7 (OEL 7)
  • Oracle Linux 8 (OEL 8)

Software requirements

  • The iptables service must be available and running.
  • The firewalld must be available and running.

Port requirements

The recovery portal requires the following ports when you use disk encryption policies. For additional Enforce port information, see Required ports.

Inbound 443 TCP Required only when you use the recovery portal with disk encryption policies. Allows users to access the recovery portal.
Outbound 443 TCP Required only when you use the recovery portal with disk encryption policies. Allows the recovery portal to access the Tanium Server.

Hardware requirements

  • CPU: 4 Cores
  • RAM: 8 GB
  • Hard Drive: 80 GB

Rules configured during installation

The installation script configures the following rules:

  • CentOS 6, RHEL 6, and OEL 6:

    iptables -I INPUT 1 -p tcp --dport 443 -j ACCEPT

    iptables -I INPUT 2 -p tcp --dport 3000 -j ACCEPT

    iptables -A PREROUTING -t nat -p tcp --dport 443 -j REDIRECT --to-port 3000

    iptables -A OUTPUT -t nat -o lo -p tcp --dport 443 -j REDIRECT --to-port 3000

    service iptables save

  • CentOS 7, CentOS 8, RHEL 7, RHEL 8, OEL 7, and OEL 8:

    firewall-cmd --add-port=443/tcp --permanent

    firewall-cmd --permanent --direct --add-rule ipv4 nat OUTPUT 0 -p tcp -o lo --dport 443 -j REDIRECT --to-ports 3000

    firewall-cmd --add-forward-port=port=443:proto=tcp:toport=3000 --permanent

    firewall-cmd --reload

Supported IdPs for SAML authentication

  • Okta
  • Azure AD
  • Oracle
  • ADFS

Install and configure

The recovery portal requires SAML authentication, both Server Provider initiated SSO and Identity Provider initiated SSO. For more information on how the Tanium Console integrates with a SAML IdP, refer to the Tanium Console User Guide: Integrating with a SAML IdP.

Prerequisites

  1. You must create the following SSL certificates for the server to use:
    • tanium-enforce-recovery-portal.crt
    • tanium-enforce-recovery-portal.key
  2. Obtain this certificate from your IdP:
    • saml-idp.crt
  3. After you have the SSL certificates, copy them to the /var/www/tanium-enforce-recovery-portal/certs directory on the recovery portal server. Create the directory if it does not exist.

Configure the Recovery Portal

You must have Enforce Recovery Portal Administrator privileges to configure and edit these settings. See User role requirements.

  1. From the Enforce Overview page, click Settings and then click Recovery Portal.
  2. Click Edit, and enter the following information for the recovery portal server:
    1. Enter the Host Server IP Address. This is the address of the recovery portal server.
    2. Enter the SAML Entry Point. Obtained from your IdP, this is the URL where the recovery portal sends the SAML request. (the IdP SSO URL) For example, https://login.microsoftonline.com/<objectId>/saml2.
    3. Enter the SAML Issuer. The issuer entity identifier of the recovery portal sent in the authentication request. For example: http://www.recovery-portal.com/YWJjZGVmMTIzNA. The value must match the sec_assertion_allowed_issuer and sec_response_allowed_issuer values.

      This is usually Entity Id on IdP consoles.

    4. Enter the SAML Groups Claim Field. This is the name of the groups attribute in the SAML response.

      5. For Okta, you must add a GROUP ATTRIBUTE STATEMENT to the application.

    5. Enter the SAML Callback URL. Provide this to your IdP. This is the URL where the SAML provider sends its response. It should be in the following format: <recovery portal URL>/api/v1/saml2/auth/callback. For example, https://myrecoveryportal.com/api/v1/saml2/auth/callback.

      6. This is usually the ACS url on IdP consoles.

    6. Enter the Login Help Text. This text is displayed at the bottom of the screen.

    7. (Optional) If you want to use a custom logo for the recovery portal sign in page, click Browse for file and upload it.

      Supported file types for the logo are JPG, JPEG, SVG, GIF, and PNG.

    8. (Optional) If you want to add a shortcut icon, also referred to as a favicon, for the recovery portal, click Browse for file and upload it. This file must be named favicon.ico.

    9. Enter the Minimum Key Length, which determines the minimum length of the key ID that must be entered before auto-complete results display.

    10. Optionally, enter an Allowed Security Group. Members of this group can search all recovery keys. Users who are not a member of this group can search only for their own recovery keys (based on the username that is used to authenticate with the recovery portal). This field is case-sensitive.

    11. Click Save and installation file creation begins.

  3. After the file is available, click Download Installation File to download the recovery portal installation file, enforce-recovery-portal.tgz.





    The download file is available for 30 minutes after it is created. Click Download Installation File to download the file. When the download file expires, click Create Installation File, which becomes available after 30 minutes, to enter settings and create a new download file.

  4. Upload the recovery portal installation file to a location on the server that hosts the recovery portal.

    Use the home directory on the server.

  5. Change to the location where you uploaded enforce-recovery-portal.tgz and extract the files: rm -rf tanium-enforce-recovery-portal && tar xzf enforce-recovery-portal.tgz.
  6. Change to the directory where you extracted the files: cd tanium-enforce-recovery-portal.
  7. Make the installation script executable: chmod +x install.sh.
  8. Run the installation script using sudo: sudo ./install.sh.
    As the script runs, you are prompted for the following details:
    1. Specify a user for the server. The default value is the user running the script.

      This user should not be root or have sudo rights.

    2. Specify a group for the server. The default value is the user running the script.
    3. Confirm the Tanium server host address.
    4. Enter the Tanium server username and password for the recovery portal server.

      5. This user should not have Tanium administrator permissions. Create a Tanium server user account for the recovery portal with Enforce Recovery Portal as the only role granted.

  9. After the installation script runs, check the status of the recovery portal using the following command: systemctl status tanium-enforce-recovery-portal.service

    10. You can also check the status of the recovery portal from the Settings > Recovery Portal tab.

The nameID format from the IdP application user name and the format for the recovery key viewer must match. For example, if user names in the recovery key viewer are formatted as firstname.lastname, then the IdP format must also be firstname.lastname. If the IdP application uses the format [email protected], then the recovery key viewer must use [email protected]. If these formats do not match, users cannot view their keys.

Replace the SSL certificates

Complete these steps on the machine hosting the recovery portal to replace expiring SSL certificates.

  1. Run this command to stop the recovery portal service: sudo systemctl stop tanium-enforce-recovery-portal.service.
  2. Rename the existing certificates using these commands:
    1. mv /var/www/tanium-enforce-recovery-portal/certs/tanium-enforce-recovery-portal.crt /var/www/tanium-enforce-recovery-portal/certs/tanium-enforce-recovery-portal-crt.old
    2. mv /var/www/tanium-enforce-recovery-portal/certs/tanium-enforce-recovery-portal.key /var/www/tanium-enforce-recovery-portal/certs/tanium-enforce-recovery-portal-key.old
  3. Run these commands to copy the new certificates to the correct directory:
    1. cp <path to file>/tanium-enforce-recovery-portal.crt /var/www/tanium-enforce-recovery-portal/certs
    2. cp <path to file>/tanium-enforce-recovery-portal.key /var/www/tanium-enforce-recovery-portal/certs
  4. Run these commands to start the recovery portal service:
    1. systemctl start tanium-enforce-recovery-portal.service
    2. systemctl status tanium-enforce-recovery-portal.service

Uninstall

To uninstall the recovery portal, run ./uninstall.sh in the /var/www/tanium-enforce-recovery-portal directory.

The uninstallation process deletes the portal certificates located in the /var/www/tanium-enforce-recovery-portal/certs directory. If you want to preserve these certificates, you should copy them before uninstalling.

End user self-service workflow with SAML

With Service Provider initiated SSO, end users access the recovery portal URL and click the Log in with SSO link, which redirects users to the identity provider where they enter their SSO credentials. After authentication, users are redirected back to the recovery portal where they are prompted to select their operating system to proceed.

Troubleshooting the recovery portal

Log files for the recovery portal are located in the /var/www/tanium-enforce-recovery-portal/logs directory.

Note that some service startup errors can appear in the service. Run the following command to print the service logs:

journalctl -u tanium-enforce-recovery-portal.service -b --no-pager

In the event that the recovery portal loses communication with the Tanium server because the API token has expired, run the following command and provide the portal username and password when prompted:

/bin/bash /var/www/tanium-enforce-recovery-portal/app/reset-api-token.sh