ThinLinc SSH

Setting up ThinLinc with the Groove.id SSH Agent

You can use Groove.id to manage access to a Cendio ThinLinc environment. In this tutorial, you will use the Groove.id Linux User agent to configure accounts and SSH public keys on the server. Clients will use the Groove.id SSH Agent package to connect via SSH.

Configure the Server

  1. Navigate to Apps > New and create a new Linux User account.

  2. Download and install the Groove.id package for your Linux flavor.

   wget https://auth.example.com/download/stable/grooveid.x86_64.rpm && \
   sudo rpm -ivh grooveid.x86_64.rpm
  1. Configure the service by editing /etc/grooveid/localuser.conf to contain the required text, something like:
   echo 'service-token: "SERVICE_TOKEN"' > /etc/grooveid/localuser.conf
  1. Start the service with the following command:
   sudo systemctl start grooveid-localuser
  1. Edit /etc/ssh/sshd_config to direct the SSH server at the key files Groove.id manages.
   AuthorizedKeysFile "/var/spool/grooveid/localuser/ssh_authorized_keys/%u"
  1. Then restart the ssh service with the command:
   sudo systemctl restart sshd

Enable Accounts

On the Groove.id console, in the Linux User app that you created, navigate to Accounts.

You can now enable any users that you’d like to have accounts on the new system.

Note that when the agent first connects, it may take a few moments for existing accounts to synchronize. You can press the Refresh button to accelerate this process.

Configure Clients

Install Groove.id SSH Agent

  1. In the Groove.id console, navigate to the SSH tab.

  2. Download the Groove.id agent for your operating system. Provide the value for Server Identifier given in the Groove.id console, e.g. signin.example.com.

  1. Test the Groove.id SSH agent by right clicking on the Groove.id icon in the task tray and choosing Sign In. A web browser will open where you’ll sign in.

Configure ThinLinc Client

  1. Install ThinLinc as normal.

  2. Configure the client to connect to your server

  1. Press Options, choose the Security tab and select Kerberos Ticket as the Authentication method.
  1. When you press Connect, ThinLinc will use the Groove.id SSH agent to connect to your server.

Technical Internals

The ThinLinc client connects to the server via SSH using an embedded version of OpenSSH. Unfortunately, the version of OpenSSH that ThinLinc ships does not support the SSH agent authentication, which is what Groove.id uses to implement SSH.

When you install the Groove.id SSH agent, it replaces the bundled version of OpenSSH with our own version, named grooveid-tlssh. The replacement is done by setting values under the registry key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\ssh.exe\GrooveidThinlincSshReplacement.

You can remove this replacement and use the ThinLinc-provided SSH client with the following command:

> grooveid-tlssh -uninstall-replacement

To re-activate the Groove.id replacement SSH-client, run:

> grooveid-tlssh -install-replacement

A word about Kerberos

Although we select Kerberos ticket as the authentication method, we aren’t really using Kerberos. We select this option because it causes the ThinLinc UI to display only a username box, and because Kerberos is rarely used these days.

When you select Kerberos, ThinLinc passes the command line option -o gssapiauthentication=yes to the embedded SSH client. grooveid-tlssh looks for this command line option and interprets it as a signal to use the Groove.id SSH Agent to connect.

Troubleshooting

The replacement SSH client writes log files whose names match grooveid-ssh-client-*.log to %TEMP%. You can increase the logging level by setting the environment variable GROOVEID_TLSSH_TRACE=true.

Last modified May 12, 2020: refactor docs (d7a7a5c1d)