TLS Certificate HOWTO

Questions?

Email our fast, friendly support if you have a question not covered here: [email protected].

TLS Certificate HOWTO

NOTE: Userify 6.0 and later now offer built-in LetsEncrypt integration for painless signed certificates. The below information is still valid for your own custom certificates such as wildcard certs.

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.

Certificate Box

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 protected] if you have questions or need installation support.

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.

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

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.

Help!

Fast, free support is just a click away

Start managing your users and SSH keys in seconds     Try for free