Host keys and certificates for secure RDP and SSH in Remote Access

This page is for the administrator who owns Remote Access resources. It explains how SSOGEN decides that the host at the other end of a session is the one you meant, and what to do when that identity changes. Setting a resource up end to end is in Remote Access to SSH, RDP and VNC hosts.

Who can do this. A Super admin only. Trusting a host is an administrator’s act: a person opening a session is never asked to accept a host key or certificate, and cannot.

What is needed first. A Gateway group that can reach the host, and the host’s own fingerprint from a source you trust (for SSH, the output of ssh-keygen -lf run on the host; for RDP, the SHA-256 of the desktop’s certificate as the host shows it).

The result. The Gateway opens a session only while the host presents the key or certificate you pinned. If anything else answers at that address, nothing is sent to it, the person is told, and you see it on the timeline.

The examples use the fictional company Acme Corp and the servers Acme Build Server (SSH) at build01.acme.example and Finance desktop (RDP) at fin-rdp01.acme.example.

How trust works

Nothing is trusted on first use. A resource whose host has not been trusted refuses every session until you trust it. The person sees “This resource is not ready yet. An administrator has to confirm its host first.”
A pin is a fingerprint. For SSH it is the host key fingerprint, in the form SHA256: followed by 43 characters. For RDP and VNC it is the SHA-256 of the server certificate, 64 hexadecimal characters. A resource can hold up to 16 pins.
An RDP or VNC certificate can also be checked against an issuer. The optional Server certificate trust bundle holds the certificate authority that issued the desktop’s certificate, which must name the host. With a bundle, pins only narrow which certificates are accepted; without one, a pinned certificate is trusted as it is, so a self-signed Windows certificate works.
VNC has an identity to pin only with a security method that uses a server certificate. The console shows the certificate fields for those methods only; other VNC methods have no host identity, and the console asks you to acknowledge that.
A stored account goes only to a verified host. If the resource signs people in with a stored account, the host must be pinned; see Stored accounts and rotation.

Trust a host the first time

There are three ways. All three end in the same place: a pin on the resource.

Enter the fingerprint when you add the resource

In the Admin Console, choose Secure access > Remote Access and select Add resource.
Choose the type, fill in Resource id, Name, Application, Gateway group, Host (“one exact hostname or IP”) and Port.
Under Host identity, keep Verify the host (recommended).
- SSH: enter the Host key fingerprint (SHA256:…).
- RDP: enter Certificate pins (one SHA-256 per line), and the Server certificate trust bundle if you have one.
Select Save resource. The host is trusted from the first session.

Pair the host from the resource page

Save the resource with the fingerprint field empty. The help text says: “Leave it empty if you do not have it: the first session then shows the host’s key on its timeline, where you can trust it, and no session opens until you do. Nothing is trusted on first use.”
Open the saved resource. In the fieldset Pair and test the host it says “No one can open this resource until you trust the host. Test asks the Gateway to connect to the host, without any account, and report what the host presents.”
Select Pair. The page shows “Waiting for the Gateway to reach the host…” for up to a minute, then “The host presented SHA256:…” (or the certificate’s SHA-256).
In the field Paste the output of ssh-keygen -lf on the host (SSH) or Type the certificate’s SHA-256 as the host shows it (RDP, VNC), enter the fingerprint you obtained on the host itself. The page answers “It matches.” or “It does not match what the Gateway saw.” The Trust button is enabled only when it matches.
Select Trust. The dialog Trust this host? says: “From now on the Gateway accepts this host only while it presents SHA256:…. Sessions open now are ended, because the resource changes.” Select Trust and pin.
The page says “Trusted. The next session verifies the host against it.” and the fieldset now reads “1 key is pinned.”

Trust from a session’s timeline

If somebody tried to open the resource before you trusted the host, the attempt is on the timeline.

Choose Secure access > Remote Access, open the resource and its Timeline tab (or the session from Live sessions).
Find the row The host presented its identity with the detail line “Host identity: not trusted, so the session was refused before anything was sent” and the fingerprint (“Host key: SHA256:…” or “Certificate SHA-256: …”).
Compare the fingerprint with the one the host itself shows. Then select Trust this host key (SSH) or Trust this certificate (RDP).
The dialog Trust this host’s identity? says: “From now on the Gateway accepts this host only while it presents …. Compare it with the fingerprint the host itself shows before you trust it. Sessions open now are ended, because the resource changes.” Select Trust and pin.
The row now says “Pinned. The next session verifies the host against it.”

When the host’s identity changes

A host presents a different key or certificate after it is rebuilt, its keys are regenerated, its certificate is renewed, or because something else now answers at that address.

What the person sees. The session does not open. The page says “This host has changed since your administrator trusted it, so nothing was sent to it. Ask your administrator.” No password, key or keystroke reached the host.

What you see. On the session’s and the resource’s Timeline, a row Host key did not match (SSH) or Host certificate did not match (RDP, VNC), with the fingerprint the host presented, and a Session ended row with the reason “The host’s identity did not match, so nothing was sent to it.” Sessions keep being refused until you act.

What happens to a stored password. Trusting a new identity changes what the password was stored for, so SSOGEN clears a stored password when you update the pin. The resource then shows “The stored password was cleared because the host, port, connection path or trusted host identity changed. Enter it again; until then people cannot open this resource.” A stored key is kept.

Pair the host again

Confirm on the host itself that the change is expected, and read its new fingerprint there.
Choose Secure access > Remote Access and open the resource. In Pair and test the host, select Test.
The page shows what the host presented and says: “This is not the key pinned now. No one can open a session until you press Update key.” (For a certificate: “This is not the certificate pinned now.”)
Enter the fingerprint from the host in the compare field until the page says “It matches.”
Select Update key. The dialog Update the trusted key? says: “From now on the Gateway accepts this host only while it presents …, in place of the one pinned now. Sessions open now are ended, because the resource changes.” If a password is stored, it adds: “Saving this removes the stored password, because it was stored for the host identity or address this save changes. Store it again after trusting the host.” Select Update key.
The page says “Key updated. People can open sessions again.”
If the resource had a stored password, store it again (see Stored accounts and rotation).

Update key replaces every pin on the resource with the one the host presented. Trust (on a resource with no pin, or from the timeline) adds a pin. If the Test shows the pinned key, the page says “This is the one already pinned. Nothing to change.”

You can also keep more than one pin, for example while a host’s keys are rotated, by editing the resource: the SSH field keeps “N more pinned keys … as they are”, and the RDP field takes one SHA-256 per line.

Connect without verifying the host

A resource can be saved with Don’t verify the host (insecure) under Host identity. The console states the risk: “The Gateway will connect to whatever answers at this address and accept any identity it presents. Anyone who can intercept the network between the Gateway and the host can pose as the host and read or change the session, including a password typed into it. Pin the host’s fingerprint instead whenever you can.” You must tick “Connect without verifying this host’s identity. I accept the risk.” The choice is recorded in the audit trail, every session’s timeline shows the key or certificate the host presented (“Host identity: not verified (allowed for this resource)”), and the person connecting sees “This host’s identity is not verified (allowed by your administrator).” A stored account cannot be used on such a resource.

Changing a verified resource to unverified asks for confirmation in the dialog Stop verifying this host? with the button Stop verifying, and is recorded as Host no longer verified, confirmed by an administrator.

What is recorded

Host test requested, Host identity observed by the Gateway, Host identity trusted by an administrator (with the fingerprint), Host no longer verified, confirmed by an administrator, and on every session The host presented its identity with “Host identity: verified”, “not verified (allowed for this resource)” or “not trusted, so the session was refused before anything was sent”. See Remote Access session audit.

Check it worked

Open the resource: Pair and test the host says “1 key is pinned.” (or “1 certificate is pinned.”).
Select Test: the page shows the host’s fingerprint and “This is the one already pinned. Nothing to change.”
Open the resource from My Apps as a person who may use it. The session starts without any question about the host, and its Timeline row The host presented its identity says “Host identity: verified”.

Troubleshooting

What you see	What it means	What to do
“A host key fingerprint has the form SHA256: followed by 43 characters.”	The SSH fingerprint is in another format.	Use the SHA256 form, as `ssh-keygen -lf` prints it.
“Each certificate pin is 64 hexadecimal characters.”	The certificate SHA-256 has separators or is incomplete.	Enter the 64 hex characters only.
“At most 16 certificate pins.” / “This resource already pins 16; remove one first.”	The pin limit is reached.	Remove a pin you no longer need, or use Update key to replace them all.
“That fingerprint does not fit this resource’s protocol.”	An SSH fingerprint on an RDP resource, or the reverse.	Use the right kind.
“The Gateway did not answer in a minute. Check that it is running and can reach the host, then test again.”	The Gateway did not reach the host within 60 seconds.	Check the Gateway and the network path, then Test again.
“It does not match what the Gateway saw.”	The fingerprint you typed differs from what answered at the address.	Read the fingerprint on the host again. If it still differs, do not trust: something else is answering.
“The host could not be trusted.” / “The fingerprint could not be trusted.”	The pin could not be saved.	Reload the resource and try again.
“This save would stop verifying a host that is verified now, so nothing was saved. Reload the resource and check how its host identity is verified.”	Your edit would have removed the verification without confirmation.	Reload; if you really mean to stop verifying, use Don’t verify the host (insecure) and confirm Stop verifying.
A person sees “This resource is not ready yet. An administrator has to confirm its host first.”	No pin yet.	Pair and trust the host.
A person sees “This host has changed since your administrator trusted it, so nothing was sent to it. Ask your administrator.”	The host presented a key or certificate that is not pinned.	Follow “Pair the host again” after confirming the change on the host.
“Only a Super Admin can change this.”	Your role cannot pair or trust hosts.	Ask a Super admin.