Skip to content

Where and how to install the components#

Packages are available for the majority of linux distributions from our KIT repo server.

Some of these packages are available for Mac (via homebrew), too.

Windows ssh-client users have reported to be happy with WSL.

The examples show the installation with debian based systems. We are confident that you are smart enought to install the same package using yum, or zypper. ;)

SSH Server#

You need motley-cue and oinit-openssh, as well as oinit-ca.

The oinit-ca may also be deployed on a dedicated ssh-ca host.

apt install motley-cue oinit-openssh oinit-ca

You need motley-cue and pam-ssh-oidc.

You may remove the -autoconfig from the package name, if you want to edit files in /etc/pamd.d/ manually details here.

apt install motley-cue pam-ssh-oidc-autoconfig
To verify the installation: ssh to the host (with any username). Your client should prompt “Access Token:”, and alternate the prompt with “Password:”.

To finish up: tell sshd to trust the user-ca key:

  • echo "TrustedUserCAKeys /etc/oinit/user-ca.pub" >> /etc/ssh/sshd_config

Notice

  • You will likely want to configure the way usernames and groups are configured in Motley Cue.
  • For nginx configure ssl in /etc/nginx/conf.d/location-includer.conf

SSH-CA#

  1. The CA (oinit-ca) can be installed on the ssh-server or on a different host:
  2. Make sure that the hosts /etc/oinit/ca-config.ini connects the public-hostname with the right Motley Cue URL.
  3. oinit clients will try to find the oinit-ca by trying these locations: 1 Automatic: https://<ssh_hostname>/oinit 2 DNS: the TXT record of _oinit.<ssh_hostname> 3 Cmdline: users of oinit can specify the oinit-ca URL via 
    oint add <ssh-host>[:port] http[s]://<ca-host>[:<port>][/path]`
  4. In case the oinit-ca is not on the same host, you need to copy the user-ca public key to the ssh-server host: 
    scp <ca-host>/etc/oinit/user-ca.pub <sshd-host>/etc/ssh/
echo "TrustedUserCAKeys /etc/ssh/user-ca.pub" >> /etc/ssh/sshd_config`
    And systemctl restart ssh.service (or similar).
  5. For ensuring that ssh-certificates are correctly setup, find a good walk-through at https://bash-prompt.net/guides/ssh-certificates

Further information about oinit-ca is given under technical details.

Establishing Trust#

  1. oinit-ca will create private keys and certificates in its post-install script:
    • /etc/oinit/user-ca: Private Key of the User CA
    • /etc/oinit/user-ca.pub: Public Key of the User CA
    • /etc/oinit/host-ca: Private Key of the Host CA
    • /etc/oinit/host-ca.pub: Public Key of the Host CA
  2. (Optional) Sign the host-key with the ca:
    • Your ssh daemon also installed host-keys in its own post-install script:
    • /etc/ssh/ssh_host_*: A set of keys for different algorithms
    • Sign one of them:
    • ssh-keygen -s /etc/oinit/host-ca -I servername -h -n ssh-server,whatever /etc/ssh/ssh_host_ecdsa_key.pub
    • Tell sshd about it:
      • echo HostCertificate /etc/ssh/ssh_host_ecdsa_key.pub

Debugging#

These commands may help:

  • Inspect an ssh certificate: ssh-keygen -L -f <certificate file name>
  • oinit will store ssh-certifcates in ssh-agent. Unset SSH_AUTH_SOCK so they’re stored on disk (in $HOME/.ssh/oinit_<hostname>)

Last change: Aug 11, 2026 10:58:31