sftpgo-mirror/docs/check-password-hook.md

Check password hook

This hook allows you to externally check the provided password, its main use case is to allow to easily support things like password+OTP for protocols without keyboard interactive support such as FTP and WebDAV. You can ask your users to login using a string consisting of a fixed password and a One Time Token, you can verify the token inside the hook and ask to SFTPGo to verify the fixed part.

The same thing can be achieved using External authentication but using this hook is simpler in some use cases.

The check password hook can be defined as the absolute path of your program or an HTTP URL.

The expected response is a JSON serialized struct containing the following keys:

• status integer. 0 means KO, 1 means OK, 2 means partial success
• to_verify string. For status = 2 SFTPGo will check this password against the one stored inside SFTPGo data provider

If the hook defines an external program it can read the following environment variables:

• SFTPGO_AUTHD_USERNAME
• SFTPGO_AUTHD_PASSWORD
• SFTPGO_AUTHD_IP
• SFTPGO_AUTHD_PROTOCOL, possible values are SSH, FTP, DAV, HTTP

Global environment variables are cleared, for security reasons, when the script is called. You can set additional environment variables in the "command" configuration section.

The program must write, on its standard output, the expected JSON serialized response described above.

Any output of the program on its standard error will be recorded in the SFTPGo logs with sender check_password_hook and level warn.

If the hook is an HTTP URL then it will be invoked as HTTP POST. The request body will contain a JSON serialized struct with the following fields:

• username
• password
• ip
• protocol, possible values are SSH, FTP, DAV

If authentication succeeds the HTTP response code must be 200 and the response body must contain the expected JSON serialized response described above.

The program hook must finish within 30 seconds, the HTTP hook timeout will use the global configuration for HTTP clients.

You can also restrict the hook scope using the check_password_scope configuration key:

• 0 means all supported protocols.
• 1 means SSH only
• 2 means FTP only
• 4 means WebDAV only

You can combine the scopes. For example, 6 means FTP and WebDAV.

You can disable the hook on a per-user basis.

An example check password program allowing 2FA using password + one time token can be found inside the source tree checkpwd directory.