TLS Certificate HOWTO

Installing signed TLS certificates on Userify on-premises (Enterprise/Pro) is easy!

Userify auto-generates self-signed certificates upon server startup, but for additional enterprise integration, you can install a custom signed certificate or wildcard certificate by simply pasting the key and certificate chain into the administrative dashboard.

  1. Paste certificate and key into the server control panel.
  2. Click save and allow server to restart.
  3. Upon startup and after config load, the startup process kicks off.

The startup process validates whether the certificates and key are valid and in the correct order. If the server is unable to use the certificate and key, it will automatically switch back to its old self-signed certificate.

Important: Once you switch to signed certificates (which you should do), do not let your certificate expire. If you let the certificate expire, the shims will automatically stop accepting updates for the Userify server for security reasons. It may not be obvious that this has happened.

Shim considerations

Your servers can automatically check certificates, which increases your overall security. Managed servers will automatically start requiring properly signed certificates from the server if you paste a certificate or key (or, actually, almost anything -- even # this is a comment into the certificate and key text fields.)

Previously configured servers (before you installed a signed certificate) will not require the server to identify itself with a properly signed certificate. If you are using ACM with an ELB or ALB in front of your Userify servers, you only need to force signature checks on the server by pasting a "#comment" into each of the key and certificate fields.

You should set your hostname (under server settings) equal to the hostname that is in the Subject Alternative Name so that the shims know to expect the hostname that is offered.

Autoscaling Considerations (Enterprise w/ HS)

To ensure that an Enterprise server with the HS feature scales properly, it's only strictly required to ensure that /opt/userify-server contains the server binary itself and the base_config, which itself can be rebuilt from the web dashboard when prompted (assuming that the crypto key has been properly backed up).

Userify will rebuild any other missing components, including static files in /opt/userify-server/web, any missing certificate files, and the userify-start script.

To rotate or update the certificate, paste the new cert/key into the dashboard on a single Userify server dashboard, and ensure that all of the other servers are somehow restarted and Userify will automatically update the host.pem file on the other servers in the autoscaling group.

Port considerations.

Userify attempts to bind both port 80 and 443 on 0.0.0.0. If you're already running another proxy on those ports, Userify will warn you and continue so that you can front-end with a proxy like nginx or HA-Proxy (recommended).

Userify also binds to 8120 (also 0.0.0.0) (can be overriden on command line for multi-process operation) which is non-TLS and doesn't force an immediate 301 to 443 (like 80 does).

Based on user request, we've added capabilities to disable any of these listeners to ensure that Userify is only ever accessible via your proxy. (See ).

File ownership considerations

Everything in /opt/userify-server is set to root-only on server startup, every time, no exceptions, especially including host.pem and baseconfig.cfg. Please do not modify host.pem, since it will be modified by Userify on startup. selfsigned will be regenerated if it is removed but it could be used to populate a signed key/cert via configuration management system, as it will not be modified if exists and works. The preferred and fastest method is still through the dashboard when possible.