Obtain a certificate
On the Contributor path, you obtain the TLS certificate for Citrix SecurSpaces™ before you deploy. You also repeat this procedure at every renewal. On the Owner path, skip this page: the deployment obtains the certificate for you.
This page uses certbot and Let's Encrypt. A certificate from your organization's own certificate authority also works if it is issued for the same two names.
The two names
| Name | Example |
|---|---|
<hostname> |
securspaces.apps.example.com |
*.proxy.<hostname> |
*.proxy.securspaces.apps.example.com |
Obtain a certificate for these two names only, for this platform. A wildcard name must be validated over DNS, so you need permission to create
TXT records in your zone.
Set your values and install certbot
export ZONE=apps.example.com
export HOST=securspaces.apps.example.com
export EMAIL=you@example.com
python3 -m venv "$HOME/cbenv" && "$HOME/cbenv/bin/pip" -q install certbot
export CB="$HOME/cbenv/bin/certbot"
The email address is used for account recovery. Let's Encrypt does not send expiry reminders. SecurSpaces warns administrators before the certificate expires.
Rehearse against staging first
Let's Encrypt allows five failed validations for each name per hour. A mistyped record or a step taken too early uses one. For your first run, add these two options to the command in the next section, then remove them for the real certificate:
--server https://acme-staging-v02.api.letsencrypt.org/directory
--config-dir "$HOME/certbot-staging/config"
Never install a staging certificate. It chains to a test root, so every browser warns.
Request the certificate
"$CB" certonly --manual --preferred-challenges dns \
-d "$HOST" -d "*.proxy.$HOST" \
--agree-tos -m "$EMAIL" --no-eff-email \
--config-dir "$HOME/certbot/config" \
--work-dir "$HOME/certbot/work" \
--logs-dir "$HOME/certbot/logs"
Keep
$HOST as the first -d option. The output folder is named after it.
certbot asks you to create two
TXT records, one at a time:
| Record | Values |
|---|---|
_acme-challenge.<hostname> |
One |
_acme-challenge.proxy.<hostname> |
One |
Create the second record alongside the first. Do not replace it. At each prompt, press Enter only after that prompt's record is live.
To check that a record is live, ask the zone's own name servers. A recursive lookup can return a cached "does not exist" answer for up to an hour, which is expected:
export ZONE_NS=$(dig NS "$ZONE" +short | head -1)
dig +norecurse @"$ZONE_NS" _acme-challenge."$HOST" TXT +short
dig +norecurse @"$ZONE_NS" _acme-challenge.proxy."$HOST" TXT +short
After certbot reports success, you can delete both
TXT records.
Check the files
cd "$HOME/certbot/config/live/$HOST"
openssl crl2pkcs7 -nocrl -certfile fullchain.pem | openssl pkcs7 -print_certs -noout
diff <(openssl x509 -in fullchain.pem -noout -pubkey) <(openssl pkey -in privkey.pem -pubout) && echo MATCH
| File | Use |
|---|---|
fullchain.pem |
The certificate. Paste this one into the wizard |
privkey.pem |
The private key |
cert.pem |
Do not use. It has no issuer chain and breaks some clients |
The chain is correct when the first
subject= is your hostname and every issuer= line matches the subject= of the next certificate. The second command must print MATCH.
Keep both files and the
$HOME/certbot/config folder. The deployment does not give them back to you. Treat privkey.pem as a secret.
Paste the certificate into the wizard
On the Basics tab, select Contributor - I bring my own TLS certificate. On the Hostname tab, paste the full contents of
fullchain.pem into TLS certificate (PEM fullchain) and of privkey.pem into TLS private key (PEM). The certificate and key are stored as secure parameters and are not written to the deployment log.
At renewal
Run this procedure again from the start. If certbot offers to keep the existing certificate, choose to renew and replace it, or add
--force-renewal. Then install the new certificate as described in Renew the TLS certificate.