Reference: Encryption management recovery portal

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.

As a best practice, this website should not be hosted on the same machine as the database that is used to store the recovery keys.

Requirements

Supported operating systems

Software requirements

Hardware requirements

Supported operating systems

  • CentOS 7
  • CentOS 8
  • RHEL 7
  • RHEL 8

Software requirements

For both CentOS and RHEL:

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

Make sure all required ports are open. See Required ports.

Hardware requirements

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

Rules configured during installation

The install script configures the following rules:

  • CentOS 6 and RHEL 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 and RHEL 7:

    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

Installation and configuration

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.

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. Once you have the SSL certificates, copy them to the /etc/ssl/certs directory on the recovery portal server.

  4. Change (chown) the ownership to the user:group that will be running the recovery portal service.

  5. chmod the certificates to 400.

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 .
  2. Click the Recovery Portal tab.
  3. 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. This is the 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.

      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.

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

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

    8. Enter the Login Help Text. This is text that displays at the bottom of the login screen.

    9. (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.

    10. (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.

    11. Enter the Minimum Key Length. Determines the minimum length of the key ID that must be entered before auto-complete results display.

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

    13. Click Save and installation file creation begins.

  4. The download button becomes active once the file is available. Click Download Installation File to download the recovery portal installation file, enforce-recovery-portal.tgz.
  5. The download file is available for 30 minutes after it is created. Use the Download Installation File button to download the file. When the download file expires, use the Create Installation File button, which becomes available after 30 minutes, to enter settings and create a new download file.

  6. Upload the recovery portal installation file to a location on the server that will host the recovery portal. As a best practice, use the home directory.
  7. Change to the location where you uploaded enforce-recovery-portal.tgz.
  8. Extract the files: rm -rf tanium-enforce-recovery-portal && tar xzf enforce-recovery-portal.tgz.
  9. Change to the directory where you extracted the files: cd tanium-enforce-recovery-portal.
  10. Run the install 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 privileges. This should be a Tanium server login user account created for the recovery portal with Enforce Recovery Portal as the only role granted.

  11. After the install script runs, check the status of the recovery portal using the following command: systemctl status tanium-enforce-recovery-portal.service
  12. 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 don't match, users will not be able to view their keys.

Uninstall

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

The uninstall process deletes the portal certificates located in the /etc/ssl/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. This redirects users to the identity provider where they enter their SSO credentials. Once authenticated, 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/log/tanium-enforce-recovery-portal 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