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

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.

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

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

  9. After the install script runs, run this command in the current console: source ~/.bash_profile.
  10. Edit the configuration file, /var/www/protect-recovery-portal/ecosystem.config.js, and update the following LDAP variables to configure authentication for the recovery portal through your LDAP server:
    • LDAP_SERVER_URL
    • LDAP_BIND_DN
    • LDAP_BIND_CREDENTIALS
    • LDAP_CA_FILE
    • LDAP_SEARCH_BASE
    • LDAP_SEARCH_FILTER
    • LDAP_USERNAME_FIELD
  11. Update the following parameters in ecosystem.config.js to configure the recovery portal:
    • 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).
  12. Run this command to start the portal services: cd /var/www/protect-recovery-portal && pm2 start && pm2 save.

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