SSHUserAuthRequest Event

Fires when a client attempts to authenticate a connection.

Syntax

sftpserver.on('SSHUserAuthRequest', [callback])

Callback

The 'callback' is called when the 'SSHUserAuthRequest' event is emited.

function(e){ }

The argument 'e' has the following properties:

e.connectionId
e.user
e.service
e.authMethod
e.authParam
e.accept
e.partialSuccess
e.availableMethods
e.homeDir

Remarks

The SSHUserAuthRequest event fires when an SSH client attempts to authenticate itself on a particular connection. ConnectionId will identify the connection being authenticated. User will be the name of the account requesting authentication, and Service will contain the name of the service the client is wishing to access.

AuthMethod will denote which method the client is attempting to use to authenticate itself. AuthParam will contain the value of the authentication token used by the client. If the token is acceptable, you may set Accept to true to allow the SFTPServer to authenticate the client. If it is not, set Accept to false.

Connecting clients will initially attempt authentication with an AuthMethod of "none". This is done with the expectation that the request will fail and the server will send a list of supported methods back to the client. In your implementation check the AuthMethod parameter, if it is "none" you should set AvailableMethods and reject the request. The client will select one of the available methods and re-authenticate.

You may set AvailableMethods to a comma-delimited string of authentication methods that are available for the user. This list will be sent back to the client so that it may perform further authentication attempts.

The following is a list of methods implemented by the class:


none	This authentication method is used by most SSH clients to obtain the list of authentication methods available for the user's account. In most cases you should not accept a request using this authentication method.
password	AuthParam will contain the user-supplied password. If the password is correct, set Accept to true.
publickey	AuthParam will contain an SSH2 public key blob. If the user's public key is acceptable, set Accept to true. The class will then handle verifying the digital signature and will respond to the client accordingly.
keyboard-interactive	SSHUserAuthRequest will fire multiple times for keyboard-interactive authentication: It will fire once for each response sent by the client in the SSH_MSG_USERAUTH_INFO_RESPONSE packet (one for each prompt specified by the daemon). The index of each response will be specified as a suffix in AuthMethod, with AuthParam containing the response to the corresponding prompt (e.g keyboard-interactive-1, keyboard-interactive-2 and so on). Finally, SSHUserAuthRequest will fire one last time with AuthMethod set to "keyboard-interactive" and AuthParam set to an empty string. The daemon must set Accept to true every time to allow the authentication process to succeed.

In the case the user authentication succeeds, you may set HomeDir to the virtual path representing the initial directory for the user. If not set, the initial directory will be RootDirectory.

The PartialSuccess parameter is only used when multi-factor authentication is needed. To implement multi-factor authentication when this event fires first verify the AuthParam for the given AuthMethod. If accepted, set PartialSuccess to true and Accept to false. The client should then send the authentication request for a different form of authentication specified in AvailableMethods. You may continue to set PartialSuccess to true until all authentication requirements are satisfied. Once all requirements are satisfied set Accept to true.

Note: Processing long-running requests, including sending channel data, inside this event may cause the underlying transport to stop processing SSH data until the event returns. In order to prevent this from happening, all requests should be processed asynchronously in a separate thread outside of this event.