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.
- Paste certificate and key into the server control panel.
- Click save and allow server to restart.
- 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.
Paste your issued certificate (.crt) file for your hostname and domain name first, at the top of the certificate textbox.
Then, add one or more blanks lines between certificates and paste all of the other chained certificates, in order from most specific to the least specific. (Most specific go at the top, and least at the bottom.)
For example, if you have your freshly issued certificate for userify.example.com, and also the AlphaSSL and Comodo certificates, paste them in this order:
- userify.example.com (signed by AlphaSSL)
- AlphaSSL (signed by Comodo)
- Comodo (although usually optional.)
Important: Do not let your certificate expire. If you let the certificate expire, the shims will automatically stop accepting updates for the Userify server because the certificates are no longer valid, and it may not be obvious that this has happened, because you'll still be able to log into some servers but not others.
Integration with NGINX or other load balancers
(The below applies to AWS Elastic Load Balancers and other load balancers as well as NGINX.)
If you are integrating with NGINX in front of your Userify server (recommended), then you should configure your TLS certificate through NGINX.
If you are on a single server and just using NGINX for performance and security, you can continue to use Userify to write your certificate files for you. In this case, just point NGINX at the Userify certificates in /opt/userify-server/host.pem or /opt/userify-server/self-signed.pem. (Our pre-built NGINX configuration does this automatically.)
If you are configuring your TLS certificate through NGINX and just want to use Userify self-signed between NGINX and Userify, then just place the word "override" in the Userify certificate and secret box. This will cause Userify to require the shims to validate the certificate (such as https://userify.example.com) but it will tell Userify that certificate/secret are being managed elsewhere (in NGINX or other load balancer.)
There are other possible configurations as well; please contact email@example.com if you have questions or need installation support.
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.
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.