skip to content

With OpenSSH's sshd, how does AuthenticationMethods publickey,keyboard-interactive require both a key and a one-time code, and why keyboard-interactive rather than password?

level: seniorimportance: should knowfreq 14%

answer

  1. comma means then, space means or
  2. partial success in the failure reply
  3. server-defined prompts
  4. PAM behind the prompts
  5. SSH_MSG_USERAUTH_INFO_REQUEST

basics

~20 s

AuthenticationMethods publickey,keyboard-interactive makes sshd accept a valid key first, answer it with partial success, then require a keyboard-interactive round. Keyboard-interactive (RFC 4256) carries prompts the server chooses, so a PAM module can ask for a one-time code.

solid answer

~50 s

`AuthenticationMethods` takes one or more space-separated lists; commas inside a list mean every method must succeed in that order, and completing any one list grants access. With `publickey,keyboard-interactive` sshd offers only `publickey` at first. When the key signature verifies, it replies `SSH_MSG_USERAUTH_FAILURE` with **partial success** TRUE and `keyboard-interactive` as the method that can continue, and it sends `SSH_MSG_USERAUTH_SUCCESS` only after the second step. Keyboard-interactive (RFC 4256) lets the server send `SSH_MSG_USERAUTH_INFO_REQUEST` messages with any prompts it chooses, which is how a PAM stack asks for a one-time code, or a password and then a code. The `password` method carries one string per request and has no way for the server to ask its own questions. Each listed method must also be enabled, and keyboard-interactive needs a back end such as PAM (`UsePAM yes`; the upstream default is `no`).

code

ini · 7 lines
ini
# sshd_config: everyone else keeps the default (any single method)
UsePAM yes
KbdInteractiveAuthentication yes

# Break-glass account: a key first, then a PAM one-time-code prompt
Match User breakglass
    AuthenticationMethods publickey,keyboard-interactive:pam

go deeper

for a junior

Recall that SSH can require more than one method in a row, for example a key and then a code, and that keyboard-interactive is the method that shows server-chosen prompts.

for a middle

Explain the grammar and the wire: commas chain, spaces offer alternatives, partial success signals the next step, and info requests carry the prompts and their echo flags.

for a senior

Show you can build a break-glass account safely: a Match block, the methods actually enabled, PAM deciding the prompts, and checking that no list can be completed with one secret alone.

for a principal

Weigh where the second factor lives: a PAM prompt is easy to add but trusts the host's PAM stack, while hardware keys or short-lived certificates move assurance elsewhere.

## The directive's grammar In OpenSSH's sshd, `AuthenticationMethods` lists what must succeed before a user is let in. The default value, `any`, accepts any single enabled method. Otherwise it takes **one or more lists separated by spaces**, each list being **method names separated by commas**: | Value | Meaning | |---|---| | `any` | one successful method of any enabled kind (the default) | | `publickey,keyboard-interactive` | a key, **then** a keyboard-interactive round | | `publickey,password publickey,keyboard-interactive` | a key, then **either** a password **or** keyboard-interactive | | `publickey,publickey` | two **different** keys; sshd refuses reuse of a key already used | | `publickey,keyboard-interactive:pam` | as above, with keyboard-interactive tied to the PAM device | Only methods that are **next** in at least one list are offered at each stage, so with `publickey,keyboard-interactive` a client cannot try the code before the key. The directive is allowed inside a `Match` block, which is how one account, such as a break-glass account, can demand more than everyone else. The man page adds a condition that is easy to miss: each listed method must **also be enabled** in the configuration. ## How RFC 4252 carries a multi-step login RFC 4252 was written for this. Each step uses the ordinary messages: 1. The client sends a `publickey` request with a signature over the session identifier. 2. The key checks out, but policy wants more, so the server answers `SSH_MSG_USERAUTH_FAILURE` with **partial success = TRUE** and the name-list `keyboard-interactive`, the methods that can continue. 3. The client starts `keyboard-interactive`. The server sends `SSH_MSG_USERAUTH_INFO_REQUEST` with a name, an instruction, and one or more prompts, each with an **echo** flag. 4. The client shows the prompts, the user types the code, and the client returns `SSH_MSG_USERAUTH_INFO_RESPONSE`. The server may send further info requests. 5. Only when every method in a list has succeeded does the server send `SSH_MSG_USERAUTH_SUCCESS`, exactly once. The client needs nothing special. OpenSSH's `ssh` tries methods in its `PreferredAuthentications` order (by default `gssapi-with-mic,hostbased,publickey,keyboard-interactive,password`) among those the server says can continue. ## Why keyboard-interactive and not password | | `password` (RFC 4252) | `keyboard-interactive` (RFC 4256) | |---|---|---| | Who chooses the prompt | the client, which asks for a password | the server, prompt by prompt | | Rounds | one string per request (plus an optional password change) | as many info requests as the server needs | | Fit for "password, then code" | no, a single value only | yes | | Echo control | none | an echo flag per prompt | | sshd switch | `PasswordAuthentication` | `KbdInteractiveAuthentication` (alias `ChallengeResponseAuthentication`, deprecated) | RFC 4256's stated goal is to let the client know **little or nothing** about the mechanism behind the prompts, so the server can change it without updating clients. That is exactly what a one-time-code check needs: the server decides what to ask, and the client relays the questions and answers. ## Where PAM sits - On sshd, keyboard-interactive is served by a back end: **PAM**, or BSD authentication on systems that have it, selectable with the `:pam` or `:bsdauth` suffix in `AuthenticationMethods`. - `UsePAM yes` enables PAM for both `KbdInteractiveAuthentication` and `PasswordAuthentication`, plus PAM account and session processing for every method. The upstream default is `no`, so check the configuration your system actually ships. - The PAM stack, not sshd, decides which prompts appear. If it asks for the Unix password and a code, the user sees both; if it asks only for a code, the key plus the code are the two factors. - With `UsePAM yes`, the man page warns that PAM keyboard-interactive usually plays the same role as password authentication, so leaving both enabled on their own gives two doors to one secret. Which methods to switch off server-wide is a hardening decision covered with sshd hardening; here the point is what each method proves. ## A break-glass account ```ini UsePAM yes KbdInteractiveAuthentication yes Match User breakglass AuthenticationMethods publickey,keyboard-interactive:pam ``` For everyone else the default `any` still applies. For `breakglass`, a stolen key alone gets only a prompt for a code, and a phished code alone gets nothing. ## Edge cases worth knowing - A FIDO security key protected by a PIN is still **one** factor to sshd; to demand two, list two methods here. - `publickey,publickey` makes sense when two people each hold one key, since sshd will not accept the same key twice. - If a listed method is disabled elsewhere in the configuration, that list can never complete; if it is the only list for that user, nobody can log in as them.

  • What does OpenSSH's sshd require for AuthenticationMethods publickey,publickey?
    Two successful public-key authentications with two different keys. The man page says that when publickey is listed more than once, sshd verifies that keys already used successfully are not reused for later steps.
  • During a two-step SSH login, does the client need configuring to continue after the key?
    Usually not. Per RFC 4252, the server answers the successful key with SSH_MSG_USERAUTH_FAILURE, partial success TRUE, naming the methods that can continue, and the client carries on with one it supports. OpenSSH's client picks from its PreferredAuthentications order among those methods.
  • Why can a keyboard-interactive prompt show a code as it is typed while hiding a password?
    RFC 4256 gives every prompt in SSH_MSG_USERAUTH_INFO_REQUEST its own echo flag, and clients should echo or mask each prompt independently. The server, through PAM, decides which answers are secret.

  • A comma in AuthenticationMethods means any one of the methods is enough.
  • After the key succeeds sshd sends SSH_MSG_USERAUTH_SUCCESS, then asks for the code.
  • Listing a method in AuthenticationMethods enables it even if it is switched off.
  • The password method lets the server send its own sequence of prompts.
  • Keyboard-interactive needs a client plug-in for each kind of one-time code.