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 Postgres database that is used to store the recovery keys.

Supported operating systems

  • CentOS 6
  • CentOS 7

Software Requirements

  • CentOS 6: The iptables service must be available and running.
  • CentOS 7: firewallD must be available and running.

Make sure all required ports are open. See Ports required for Protect communication.

Hardware Requirements

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

Rules configured during installation

The install script configures the following rules:

The <Port Number> referenced in the rules is the port number that you set when you run the install script for the portal, either 80 or 443.

  • CentOS 6:

    iptables -I INPUT 1 -p tcp --dport <Port Number> -j ACCEPT

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

    iptables -A PREROUTING -t nat -p tcp --dport <Port Number> -j REDIRECT --to-port 3000

    iptables -A OUTPUT -t nat -o lo -p tcp --dport <Port Number> -j REDIRECT --to-port 3000

  • CentOS 7:

    firewall-cmd --add-port=<Port Number>/tcp --permanent

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

    firewall-cmd --add-forward-port=port=<Port Number>:proto=tcp:toport=3000 --permanent

    firewall-cmd --reload

Supported IdPs for SAML Authentication

  • Okta
  • Azure AD
  • Oracle
  • ADFS

Installation and configuration

  1. Download the recovery portal installation file, protect-recovery-portal.tar.gz:
    1. From the Protect Home page, click Settings .
    2. Click the Endpoint Encryption tab.
    3. In the Recovery Portal Download section, click Download.
  2. Upload the recovery portal installation file to a location on the server that will host the portal. As a best practice, use the home directory.
  3. Change to the location where you uploaded protect-recovery-portal.tar.gz.
  4. Extract the files: rm -rf protect-recovery-portal && tar xzf protect-recovery-portal.tar.gz.
  5. Change to the directory where you extracted the files: cd protect-recovery-portal.
  6. (Optional) If you want to use a custom logo for the recovery portal sign in page, copy the file to the protect-recovery-portal/app/web/static/logo directory.

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

  7. (Optional) If you want to add a shortcut icon, also referred to as a favicon, for the recovery portal, copy the ICO file to the protect-recovery-portal/app/web/static directory.

    The ICO file must be named favicon.ico.

  8. Run the install script as 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. Specify a port on which to run the server. Specify 443 for HTTPS or 80 for HTTP.

      If you specify 443/HTTPS, you must create SSL certificates for the server to use. After you create the SSL certificates, edit the configuration file, /var/www/protect-recovery-portal/ecosystem.config.js, and update the following TLS variables with the path to the certificate files on the recovery portal server:

      • TLS_CERT_PATH
      • TLS_KEY_PATH

      HTTPS is required if you are using Azure AD as your IdP.

  9. After the install script runs, run this command in the current console: source ~/.bash_profile. This command must be run as the user specified in the install (step 8a above).
  10. The recovery portal requires SAML authentication, both Service 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.
    To configure SAML for the recovery portal, edit the configuration file, /var/www/protect-recovery-portal/ecosystem.config.js to contain the following values. (Some of these values must be obtained from your Identity Provider.)
    11. Setting Guidelines
    IS_HTTPS Set this attribute to indicate whether the recovery portal is running HTTPS or not.
    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
    SAML_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.

    This is usually Entity Id on IdP consoles.
    SAML_CERT_PATH Obtain the certificate from your IdP. This is used to validate the SAML response.
    SAML_GROUPS_CLAIM_FIELD

    This is the name of the groups attribute in the SAML response.

    For Okta, you must add a GROUP ATTRIBUTE STATEMENT to the application.
    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

    This is usually the ACS url on IdP consoles.
  11. Update the following parameters in ecosystem.config.js to configure the recovery portal:
    12. Setting Guidelines

    LOGIN_INFO:

    		 Configures the help text that displays at the bottom of the login screen.
    MINIMUM_KEY_LENGTH Determines the minimum length of the key ID that must be entered before autocomplete results display. You must configure this parameter in both the api and web sections of ecosystem.config.js.
    PROTECT_API_FINGERPRINT

    Used for certificate pinning. Copy this value from the Endpoint Encryption tab in the Protect settings.

    This value displays after the connection to the Postgres server is verified.
    PROTECT_API_TOKEN The token used to authenticate requests against the Protect service. Set this token in the Protect Service Token field on the Endpoint Encryption tab in the Protect settings. The values in the Protect settings and the ecosystem.config.js must match.
    (Optional) ALLOWED_SECURITY_GROUP

    Members of the specified group can search all recovery keys. Users that 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.
  12. Run this command to start the portal services: cd /var/www/protect-recovery-portal && pm2 start && pm2 save.

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.

Configuration file

The configuration file for the recovery portal is /var/www/protect-recovery-portal/ecosystem.config.js. Update this file if you want to modify any of the configuration parameters for the recovery portal.

Every time you update this file, you must reload and restart the portal services with this command: cd /var/www/protect-recovery-portal pm2 stop all && pm2 delete all && pm2 start

End User Self-Service Workflow with SAML

With Server Provider initiated SSO, end users access the recovery portal URL and click the Log in with SSO button. 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.