Skip to content

Overview#

There are several mechanisms to enable SSH with federated identities. All make use of Motley Cue. Therefore, the same federated identities will be mapped to the same UNIX ID (usernames, UIDs, groups, …).

Quote

This federated approach allows users to SSH into systems using their institutional/organizational identities without managing individual SSH keys on each server.

All mechanisms require a way for the user to authenticate. We assume fresh Access Tokens being available on the client machine. The mechanism how this is achieved is external to Motley Cue. External tools, such as oidc-agent, mytoken, or htgettoken work well for this.

The supported underlying mechanisms work quite differently:

Access Token as password#

Here the user provides their OIDC access token directly to the ssh-client as password. Since tokens change often and are typically inconvenient to type, we provide two different ssh-client side helpers to improve the user experience:

  • mccli – a commandline helper to integrate Motley Cue and the ssh-client, requires installation on the client.
  • web-ssh – a web-browser based approach, which requires no installation anywhere.

For verifying the token on the ssh-server side, the pam module pam-ssh-oidc is used. It intercepts SSH authentication, forwards the password to motley_cue’s /verify_user endpoint. Motley Cue then validates the token and checks if it belongs to the specified username. If valid and authorised, SSH access is granted.

SSH Certificates#

This newer approach (oinit) makes use of ssh certificates.

Here, the user first obtains an ssh-certificate from our ssh-online-ca “oinit”. oinit interfaces with Motley Cue to provision the user, and returns an ssh-certifcate, which the user can use without any further authentication.

Also here we provide (optional) clientside tools for improving the user experience of this: oinit.

Serversice, this requires setting up ssh-certificates to trust the oinit ssh-online-ca, which is less difficult than it sounds.

Commonalities of both mechanisms#

Both approaches have a lot in common:

  • Most importantly, no ssh components are modified. Any ssh-package from any vendor should work with both approaches.
  • We support many Linux distributions, as well as clients for MacOs, Windows, and Web Browsers.
  • Both approaches do require access tokens on the client to authenticate the user. For both mechanisms a good integration with oidc-agent exists.
    While the access token based mechanism requires them on each login, the ssh-certificate based mechanism only requires valid tokens whenever an ssh-certificate expired. This expiry can be set by the admin of the ssh-server/ssh-ca, and may be significantly longer than the lifetime of access tokens.
  • Motley Cue is used in both mechanisms, to ensure that the same user will be mapped to the same UNIX account in the same way, regardless of the mechanism used.
  • Both mechanisms implement ways for removing the username from the equation.

Last change: Aug 18, 2025 11:21:32