Keyboard-Interactive Authentication
Keyboard-interactive authentication (RFC 4256) lets an SSH server ask the client any number of questions during sign-in. It is how most servers deliver a second factor: a code from an authenticator app, a YubiKey OTP, a Duo push or passcode, an RSA SecurID token. ZestSSH answers the password part for you and asks you for the rest.
This page is about two-factor sign-in on the SSH servers you connect to. Two-factor sign-in for your ZestSSH account is a separate, upcoming feature.
Availability
Section titled “Availability”| Platform | Status |
|---|---|
| Android | Full support |
| iOS | Full support |
| Windows | Full support |
| macOS | Full support |
| Linux | Full support |
What You See
Section titled “What You See”- Connect as usual.
- If the server asks for your password and one is saved, ZestSSH answers it for you.
- If the server asks for anything else, such as
Verification code:, a Sign-in step dialog appears with the host and the server’s question. Type the answer and choose Send. - Choose Cancel to stop signing in. The session closes, the same as cancelling a password prompt.
The dialog says the questions come from the server, not from ZestSSH. A server can ask for anything, so answer only what you expect it to ask.
The dialog appears for terminal sessions (and SFTP, which runs over the same connection), for each jump host on the way to a server, for serial console sessions, and for Test connection in the host editor.
How ZestSSH Answers
Section titled “How ZestSSH Answers”Your saved password
Section titled “Your saved password”A prompt gets your saved password only when it is a real password prompt: it does not echo, and its text is Password: or <user>'s password: (case-insensitive). The password is sent at most once per connection. If the server asks for a password again, the saved one was not accepted, so ZestSSH asks you instead of repeating it into an account lockout.
A prompt such as Verification code:, Passcode: or Enter PASSCODE: never receives your password, so it cannot end up in the server’s two-factor log.
Everything else
Section titled “Everything else”Every other prompt goes to you, exactly as the server wrote it, with nothing filled in.
- Answers the server marks as secret are hidden. Use the eye button to show one; in recording mode ZestSSH asks first.
- Secret answers are kept out of the keyboard’s suggestions and learning.
- Several prompts in one step appear together. Enter moves to the next field and sends from the last.
- The server’s text is cleaned before it is shown: control characters, direction overrides and invisible characters are removed, and very long text is shortened.
- Your answers are never saved or written to logs, and neither is the server’s text. The connection log records only how many questions were asked and whether you answered or cancelled.
Push approvals
Section titled “Push approvals”Some servers send a message instead of a question, for example “Pushed a login request to your phone”, and then wait while you approve on your phone. ZestSSH notes the message in the connection log and waits. Once a server has asked anything, it has up to 120 seconds to reply, instead of the usual 15.
Timing
Section titled “Timing”The 15-second sign-in timeout stops while a question is on screen. Most servers end an unanswered sign-in after about two minutes on their side (OpenSSH’s LoginGraceTime is 120 seconds by default); when that happens the dialog closes on its own. If nothing can show the question, ZestSSH gives up after three minutes.
Connections nobody is watching
Section titled “Connections nobody is watching”The Server Monitor and automations run in the background with nobody to ask. They give your saved password to a real password prompt, once, and answer every other prompt with nothing, so a server that requires a one-time code rejects them. For those, use a key that the server accepts without a second factor.
Typical Server Setups
Section titled “Typical Server Setups”| Server setup | What happens |
|---|---|
| PAM password, macOS sshd | Saved password answered automatically |
| Password, then a one-time code | Password answered; you are asked for the code |
Key, then a one-time code (AuthenticationMethods publickey,keyboard-interactive) | Key used; you are asked for the code |
| Duo push | Nothing to answer; approve on your phone |
Duo passcode or menu (Passcode or option (1-3):) | You are asked; your answer is visible as you type, as the server requests |
| Wrong saved password, and the server asks again | Saved password sent once; then you are asked |
| Password change required at sign-in | You are asked for the current and new passwords |
Security Design
Section titled “Security Design”- One shared answerer handles every connection type, so the rules above are the same for terminals, jump hosts, serial consoles, connection tests and automation.
- The saved password goes only to a real password prompt, once.
- The dialog names the host and marks the questions as the server’s, because a malicious server could ask for credentials it should not have.
- Nothing you type into the dialog is logged or stored.
- The optional worker-isolate connection mode (off by default) does not show questions yet and answers like a background connection.
Troubleshooting
Section titled “Troubleshooting”The code is refused
Section titled “The code is refused”- Check the time on your phone: authenticator codes depend on the clock.
- If the current code is about to expire, wait for the next one.
- Many servers allow only a few tries per sign-in and then disconnect. Connect again.
The dialog did not appear
Section titled “The dialog did not appear”- On a phone, the dialog shows over the terminal screen. If you left it while connecting, open the session again.
- Background connections (Server Monitor, automations) never show the dialog.
Authentication fails on a macOS server
Section titled “Authentication fails on a macOS server”macOS sshd uses keyboard-interactive authentication by default. Ensure:
- The password is saved correctly in the identity.
- The identity is assigned to the connection.
- The server’s
sshd_confighasKbdInteractiveAuthentication yes(ChallengeResponseAuthentication yeson older macOS versions).
Q: Does ZestSSH work with Google Authenticator, Authy or other TOTP codes on SSH servers? A: Yes. When the server asks for the code, ZestSSH shows its question and you type the code from your app.
Q: Why not answer every prompt with the saved password? A: A malicious server could ask for “your email password” or “your bank PIN”. ZestSSH answers only a real password prompt, once; everything else is up to you.
Q: Can automations sign in to a server that requires a one-time code? A: No. Nobody is there to type the code, so the sign-in fails. Use a key that the server accepts without a second factor.