Access Token as a Password#
This mechanism is enabled by the pam-module pam-ssh-oidc. It runs on the
SSH server, and verifies the content of the password field whenever an
ssh-authentication is requested. pam-ssh-oidc then verifies its content
with Motley Cue.
To enter the password for the user, we provide two tools to facilitate the
process mccli and web-ssh (more details below).
Login flow#
Here’s a simple ASCII diagram showing the SSH-OIDC authentication flow:
SSH with OIDC Authentication Flow
================================
SSH Client SSH Client SSH Server SSH Server
User mccli motley_cue pam-ssh-oidc
---------- ---------- ---------- ------------
| 1. ssh user@host | | |
|------------------------->| | |
| | 2. Get OIDC token | |
| | from oidc-agent | |
| | or token file | |
| 3. SSH prompt | | |
| "Enter Access Token" | | |
|<-------------------------| | |
| 4. Access Token | | |
|------------------------->| | |
| | 5. SSH auth attempt | |
| |---------------------------------------------->|
| | | 6. Intercept |
| | | password |
| | | |
| | | 7. POST /verify_user|
| | |<---------------------|
| | | 8. Validate token |
| | | Check auth |
| | | |
| | | 9. Success/Fail |
| | |--------------------->|
| | 10. Allow/Deny SSH |
| |<----------------------------------------------┘
| 11. SSH session granted |
|<-------------------------┘
Client Side#
On the client side we offer two tools.
mccli#
mccli (motley-cue command line interface) facilitates SSH access using
OIDC tokens.
To use it, users replace the ssh user@hostname with mccli ssh
hostname in step 1.
mccli implements several options to find the access token. It can use
oidc-agent, use an environment variable or look it up in a file.
Once the token is obtained, mccli contancts Motley Cue, to check if the user is authorised, and if so, which username will be assigned. This triggers Motley Cue to run a provisioning workflow. The result (deployed, rejected, or wait-for-approval) is communicated back to mccli, together with the username.
In case the access token is longer than 1024 bytes, Motley Cue returns an OTP (One Time Password) back to mccli, which then uses the OTP instead of the access token for the password.
Username obtained from Motley Cue, and password (or OTP) are fed into the
ssh-client using pexpect in step 4.
This results in a granted ssh session (step 11.).
Usage
Once installed, users simply run:
mccli ssh <hostname>
mccli supports multiple commands:
- info – get info about service
- scp – secure file copy
- sftp – secure file transfer
- ssh – remote login client
Web SSH#
If no software can be installed on the users computer, web-ssh is a good
alternative to mccli.
web-ssh (or webssh-oidc) is a web-based SSH client that uses
an “authorization code flow” with the OP chosen by the user to obtain the
access token (step 2.).
Once the token is obtained, web-ssh follows the same flow as mccli from step 4 onward.
As a result, the users do not need to install any tool on their local
computer, and can still log in to the same account as when using mccli
or ssh-certificates.
To use it, users simply point their web browser to an web-ssh-enabled server, e.g. https://ssh-oidc-web.vm.fedcloud.eu. (On this demo-server, all users are authorised, but can not do much on that service).j
Server Side#
pam-ssh-oidc#
pam-ssh-oidc is the PAM that intercepts
SSH password authentication attempts and validates them against Motley
Cue (steps 6 - 9):
When using access token for ssh, pam-ssh-oidc captures it (step 6.) and
sends it to motley_cue’s /verify_user endpoint (step 7) to check if it’s
a valid OIDC token (or OTP) for that username. If Motley Cue confirms the
token is valid and the user is authorised (step 8), pam-ssh-oidc allows the SSH
authentication to proceed (step 9), which the SSH server does, after
additional verification (step 10).
This PAM module acts as the bridge between the standard SSH server and the OIDC authentication system, making it possible to use OAuth2/OIDC tokens as SSH passwords. It is transparent to users - they simply provide their token as the password when prompted during SSH login.
Installation
Packages are available for the majority of linux distributions from our KIT repo server. To install run:
apt-get install pam-ssh-oidc
yum install pam-ssh-oidc
zypper install pam-ssh-oidc
There is also an autoconfig package available as
pam-ssh-oidc-autoconfig, which automatically applies this configuration:
pam-ssh configuration#
When using PAM, two config files are available. These files need to be installed on each ssh server.
Only when using SSH via PAM: SSH authentication integration
Add this line one the top of /etc/pam.d/sshd:
auth sufficient pam_oidc_token.so config=/etc/pam.d/config.ini
/etc/pam.d/config.ini
The PAM module needs to find the verify_user endpoint of Motley Cue. The
local directive defines that the PAM module is not trying to verify
tokens locally inside the PAM module.
[user_verification]
local = false
verify_endpoint = http://localhost:8080/verify_user
/etc/ssh/sshd_config
Ensure that either of
ChallengeResponseAuthentication yes
KbdInteractiveAuthentication yes
Note: This will enable Password Authentication, which may not be intended.
You can disable Password Authentication in /etc/pam.d/sshd by commenting
other lines starting with auth. (Also check @include statements).
The alternative is to not use the PAM module, but ssh-certificated, instead.
Last change: Aug 18, 2025 11:21:32