[Updated September 2015]
The below process was originally written for Workspace Portal 2.1 and
can be applied to vIDM. Any differences in process has been placed appropriately within the post.
VMware strongly recommends that you configure SSL certificates that are signed by a valid Certificate Authority (CA) for use by Workspace Portal.
A default SSL server certificate is automatically generated when the Workspace appliance is installed. Although you can use the default, self-signed certificate for testing purposes, it should be replaced as soon as possible for a production environment. The default certificate is not signed by a CA. Use of certificates that are not signed by a CA can allow untrusted parties to intercept traffic by masquerading as your server.
If you deploy
Workspace with the self-signed SSL certificate, the
Workspace root CA certificate must be available as a trusted CA for any client who accesses
Workspace. The clients can include end user machines, load balancers, proxies, and so on. You can download the
Workspace root CA from
https://workspacehostname.com/horizon_workspace_rootca.pem.
Before you can import a certificate, you must generate a Certificate Signing Request (CSR) and obtain a valid, signed certificate from a CA. If the CSR is not generated according to the example procedure described in this document, the resulting certificate and its private key must be available in a PEM format file.
There are many ways to obtain SSL certificates from a CA. This post shows how to use OpenSSL to generate a CSR and make a certificate available to Workspace Portal. You can use another method if you are familiar with the required tools, and they are installed on your server.
If your organization provides you with SSL certificates that are signed by a CA, you can use these certificates. If these certificates are not in the necessary PEM format, you can convert them with third party tools, such as that from
SSLShopperTo make a certificate available to Workspace Portal 2.1, three things must be done:
- Create a configuration file
- Generate a certificate signing request (CSR) from the configuration file
- Send the signing request to a CA
When the CA returns the certificate, you must import the signed certificate into Workspace Portal using the Appliance Configurator. If using a Load Balancer, you must import the signed certificate onto to the Load Balancer per the vendor's instructions, and then install the Load Balancer's Root CA Certificate on Workspace Portal.
Creating the configuration file
We will be using OpenSSL as it comes pre-installed on the Workspace Portal appliance, though you can use OpenSSL on a wide variety of operating systems,
including Windows. The below instructions will be assuming a Linux based OS.
- Login to your system that has OpenSSL installed (if using the Workspace appliance, either open a vSphere console, or SSH into the appliance).
- Create a folder to perform the certificate work in:mkdir certificates
cd certificates
- Copy openssl.cnf into that foldercp /etc/ssl/openssl.cnf openssl.cnf
- Edit the file using vi.
vi openssl.cnf
The part of the file you have to modify in order to generate a certificate request is highlighted below. For a wildcard certificate request, subjectAltName is not relevant.
[ req_distinguished_name ] # Change these settings for your
environment
countryName_default = US
stateOrProvinceName_default = Colorado
localityName_default = Broomfield
0.organizationName_default = EUC
organizationalUnitName_default = IT
[ CA_defaults ] # Change sha1 to sha512
default_md = sha512
[ req ]
default_bits = 2048
[ v3_req ]
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment,
dataEncipherment
extendedKeyUsage = serverAuth, clientAuth
subjectAltName = DNS: ext-con.company.com, DNS:
view.company.com, DNS: gtw.company.com, DNS:
services.company.com Since we will request a wildcard
certificate these additional hostnames are not of importance.
NOTE: We are not setting the commonName here, we will do that below when prompted. If you plan to not use a wildcard, consider adding your subjectAltNames
Save this file
:wq
Generating the certificate request
- Create your CSR and private key by typingopenssl req -new -nodes -out rui.csr -keyout rui.key -config openssl.cnf
- Accept the default values you configured on the .cnf file. When prompted for the common name, enter either the wildcard value, or the external name you will be referencing for Workspace from outside your network (e.g., portal.acme.com)Make sure you store your private key in a safe place. Without it, your certificate becomes useless.
- Congrats! You've successfully created a certificate signing request for a sha512 hashed, 2048-bit encrypted certificate. Now to get this CSR signed.
Send the CSR to a Certificate Authority (CA) for signing
Your CSR must be submitted to a CA in order to be issued a usable certificate. You can use either a
publicly trusted CA (GoDaddy, DigiCert, etc), or an internal CA your company has, or perhaps one you even built yourself. If you don't go with a publicly trusted CA,
there are plenty of options for setting up your own CA. The important thing to ensure is when you've been issued your certs, download them as
Base 64 encoded.
Installing the certificate
Once you've obtained your certificate(s), it's time to put it together so that Workspace can understand it. Workspace needs the certificate to be in PEM format. PEM is a widely used format these days because of its flexibility and ease of use. PEM allows you to bundle multiple certificates into a single file which a server can read and understand. This is important for Workspace. If you need to convert the certs you received to PEM format, you can use the link provided earlier in this post, or even use OpenSSL. Workspace needs at least 2 certs (usually 3) which you should have received from your CA.
Server (host) cert
Intermediate cert(s)
Root cert
This is how we will build our PEM file, with the host cert on top, any intermediate certs in the middle, and root on the bottom:
-----BEGIN CERTIFICATE-----
(Your Primary SSL certificate)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Your Intermediate certificate)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Your Root certificate)
-----END CERTIFICATE----
It's important to use a text editor like WordPad or Notepadd++ when handling these PEM files. Using something like Notepad can cause formatting issues that we certainly want to steer clear of.
Once you've built your new PEM file containing the components above, it's time to install it. If you don't have a load balancer or reverse proxy server in place, you can install this right on Workspace. This is considered
terminating SSL on the Workspace Appliance.
To do this on Workspace Portal:
- Login to the Appliance Configurator (https://your_workspace:8443), click Install Certificate
- In the Terminate SSL on Workspace appliance tab, paste the complete certificate chain (what we created above) and also include the private key in its box.
- Save the SSL certificate.
To do this on vIDM:
- In the Administration Console, click Appliance Settings
- Click Manage Configuration and enter the admin password
- Click Install Certificate
- In the Terminate SSL on Identity Manager Appliance tab, select Custom Certificate.
If you're using a Load Balancer or Reverse Proxy, you'll need to instead install the cert on that device per the vendor's instructions. Using something like NGINX is quite simple as you simply include the cert and private key path in the configuration file (See
How to Setup NGINX as a reverse proxy for Workspace Portal 2.1)
If you're using an internal CA, or otherwise a lesser known CA, it may be necessary to install the Root CA on Workspace in order for it to gain trust. Back at the
Install Certificate page, click the
Terminate SSL on a Load Balancer tab, and paste the PEM output of the Root CA here.
NOTE: if you've previously installed custom certs on Workspace itself, and are now trying to instead use a Load Balancer, you will need to first re-generate the self signed certs on Workspace before you'll be able to properly reconfigure the Workspace FQDN.
[Important]If you happen to use a KEMP load balancer with Workspace, you may run into issues configuring your FQDN after following the recommended SSL Certificate process. Please review
Kemp's Workspace Documentation which should help get the load balancer configured properly.
Related documentation and references
