Differences
This shows you the differences between the selected revisions of the page.
| ui_login_authentication 2008-12-26 | ui_login_authentication 2024-09-20 (current) | ||
| Line 1: | Line 1: | ||
| - | ====== Authentication Tab (Login Dialog) ====== | + | ====== The Authentication Page (Advanced Site Settings dialog) ====== |
| - | //Authentication tab// allows you to configure [[ssh#authentication_in_ssh|authentication]] options of SSH protocol. | + | The //Authentication page// on the [[ui_login_advanced|Advanced Site Settings dialog]] allows you to configure [[ssh#authentication|authentication]] options of SSH protocol. |
| &screenshotpict(login_authentication) | &screenshotpict(login_authentication) | ||
| - | You need to check //Advanced options// to reveal the tab. The tab is not available for [[protocols#ftp|FTP protocol]]. | + | To reveal this page you need to select SCP or SFTP file protocol on [[ui_login|Login dialog]]. |
| - | ===== Bypassing Authentication ===== | + | &toc_title_page_sections |
| - | In SSH-2, it is possible to establish a connection without using SSH's mechanisms to identify or authenticate oneself to the server. Some servers may prefer to handle authentication in the data channel, for instance, or may simply require no authentication whatsoever. | + | ===== [[bypassing]] Bypassing Authentication ===== |
| - | By default, WinSCP assumes the server requires authentication (most do), and thus must provide a username. If you find you are getting unwanted username prompts, you could try checking //Bypass authentication entirely//. | + | In SSH, it is in principle possible to establish a connection without using SSH's mechanisms to identify or prove who you are to the server. Some servers may simply require no authentication whatsoever.· |
| - | This option only affects SSH-2 connections. SSH-1 connections always require an authentication step. ((&puttydoccite)) | + | By default, WinSCP assumes the server requires authentication (we've never heard of one that doesn't), and thus must start this process with a username. If you find you are getting username prompts that you cannot answer, you could try enabling //Bypass authentication entirely//. However, most %%SSH%% servers will reject this. |
| - | ===== Attempt Authentication Using Pagent ===== | + | This is not the option you want if you have a username and just want WinSCP to remember it; It's also probably not what if you're trying to set up passwordless |
| + | login to a mainstream %%SSH%% server; depending on the server, you probably wanted [[public_key|public-key authentication]] or perhaps [[#gssapi|GSSAPI authentication]]. (These are still forms of authentication, even if you don't have to interact with them.)((&;puttydoccite)) | ||
| - | If this option is enabled, then WinSCP will look for Pageant and attempt to authenticate with any suitable public keys Pageant currently holds. | + | ===== Authentication Options ===== |
| - | This behaviour is almost always desirable, and is therefore enabled by default. In rare cases you might need to turn it off in order to force authentication by some non-public-key method such as passwords. ((&puttydoccite)) | + | ==== Attempt Authentication Using Pageant ==== |
| + | |||
| + | If this option is enabled, then WinSCP will look for [[ui_pageant|Pageant]] and attempt to authenticate with any suitable public keys Pageant currently holds. | ||
| + | |||
| + | This behavior is almost always desirable, and is therefore enabled by default. In rare cases you might need to turn it off in order to force authentication by some non-public-key method such as passwords. ((&puttydoccite)) | ||
| Learn how to use the [[public_key|Pageant]] (PuTTY's SSH authentication agent) application for public key authentication. | Learn how to use the [[public_key|Pageant]] (PuTTY's SSH authentication agent) application for public key authentication. | ||
| - | ===== Attempt TIS or CryptoCard authentication ===== | + | ==== [[ki]] Attempt keyboard-interactive authentication ==== |
| + | |||
| + | 'Keyboard-interactive' is a flexible authentication method using an arbitrary sequence of [[ui_authenticate#keyboard_interactive|requests and responses]]; so it is not only useful for challenge/response mechanisms such as S/Key, but it can also be used for (for example) asking the user for a new password when the old one has expired. ((&puttydoccite)) | ||
| + | |||
| + | WinSCP leaves this option enabled by default, but supplies a switch to turn it off in case you should have trouble with it. If your server uses keyboard-interactive authentication to ask for your password only, and you wish to allow WinSCP to reply with password entered on [[ui_login|Login dialog]], tick //Respond with password to the first prompt//. | ||
| + | |||
| + | ===== Authentication Parameters ===== | ||
| + | |||
| + | ==== [[forwarding]] Allow agent forwarding ==== | ||
| + | |||
| + | This option allows the SSH server to open forwarded connections back to your local copy of [[ui_pageant|Pageant]]. If you are not running Pageant, this option will do nothing. Learn more about [[&url(puttydoc)/Chapter9.html#pageant-forward|agent forwarding]]. | ||
| + | |||
| + | ==== [[private_key]] Private key file ==== | ||
| + | |||
| + | Use the //Private key file// box to specify [[local_path|local path]] to your [[public_key#private|private key file]] if you are going to use [[public_key|public key authentication]]. The file must be in [[public_key#private|PuTTY format]]. If the private key is passphrase-protected, you will be [[ui_authenticate#private_key_passphrase|prompted for passphrase]] once the authentication begins. | ||
| + | |||
| + | You can use [[ui_pageant|Pageant]] so that you do not need to explicitly configure a key here. | ||
| + | |||
| + | If a private key file is specified here with Pageant running, WinSCP will first try asking Pageant to authenticate with that key, and ignore any other keys Pageant may have. If that fails, WinSCP will ask for a passphrase as normal. You can also specify a public key file in this case (in RFC 4716 or OpenSSH format), as that's sufficient to identify the key to Pageant, but of course if Pageant isn't present WinSCP can't fall back to using this file itself. | ||
| + | |||
| + | The passphrase cannot be entered in advance in session settings and thus it cannot be saved to [[session_configuration#site|site]]. If you need to login to server automatically without prompt, generate a key without passphrase. Use this method carefully and only under special circumstances. | ||
| + | |||
| + | If you select a key file in a different format (OpenSSH or ssh.com), WinSCP will offer you to ==convert== the key to PuTTY format. If certificate file with the same name((but ''-cert.pub'' or ''.pub-aadcert.pub'' //(latest beta only)// &beta suffixes.)) is found, it will be automatically added to the converted key file. | ||
| - | TIS and CryptoCard authentication are (despite their names) generic forms of simple challenge/response authentication available in SSH-1 only. You might use them if you were using S/Key one-time passwords, for example, or if you had a physical security token that generated responses to authentication challenges. | + | === [[private_key_tools]] Private Key Tools === |
| - | With this switch enabled, WinSCP will attempt these forms of authentication if the server is willing to try them. You will be [[ui_authenticate#keyboard_interactive|presented with a challenge string]] (which will be different every time) and must supply the correct response in order to log in. If your server supports this, you should talk to your system administrator about precisely what form these challenges and responses take. ((&puttydoccite)) | + | Use the button //Display Public Key// to display public key in a format suitable for pasting into OpenSSH ''[[guide_public_key#configure_openssh|authorized_keys]]'' file. |
| - | ··* Unordered List Item | + | The command //Tools > Generate New Key Pair with PuTTYgen// starts [[ui_puttygen|PuTTYgen]], in which you can [[ui_puttygen#generating|generate a new private key pair]]. After you [[ui_puttygen#saving_private|save your new key pair]] in PuTTYgen, WinSCP will detect it and automatically insert a path to the new key file into //Private key file// box. |
| - | ===== Attempt keyboard-interactive authentication ===== | + | |
| - | The SSH-2 equivalent of TIS authentication is called 'keyboard-interactive'. It is a flexible authentication method using an arbitrary sequence of [[ui_authenticate#keyboard_interactive|requests and responses]]; so it is not only useful for challenge/response mechanisms such as S/Key, but it can also be used for (for example) asking the user for a new password when the old one has expired. ((&puttydoccite)) | + | Use the command //Tools > Install Public Key into Server// to [[guide_public_key#configure_openssh|install a public key into OpenSSH server]]. You will be prompted to select key pair to install. You will need to authenticate to the server to install the key. You can authenticate using a password or using another key (select it in //Private key file// box). After installing succeeds, the new private key will be inserted into the //Private key file// box. |
| - | WinSCP leaves this option enabled by default, but supplies a switch to turn it off in case you should have trouble with it. If your server uses keyboard-interactive authentication to ask for your password only, and you wish to allow WinSCP to reply with password entered on //[[ui_login_session|Session tab]]//, tick //Respond with password to the first prompt//. | + | ==== [[certificate]] Certificate to use with the private key ==== |
| - | ===== Attempt Kerberos 5 GSSAPI/SSPI authentication ===== | + | In some environments, user authentication keys can be signed in turn by a certifying authority (CA for short), and user accounts on an SSH server can be configured to automatically trust any key that's certified by the right signature. This is optional. If you don't know you need it, you can leave this blank. |
| - | The switch tells WinSCP to attempt GSSAPI or SSPI authentication. | + | This can be a convenient setup if you have a very large number of servers. When you change your key pair, you might otherwise have to [[guide_public_key#configure_openssh|edit the ''authorized_keys'' file]] (in case of OpenSSH) on every server individually, to make them all accept the new key. But if instead you configure all those servers once to accept keys signed as yours by a CA, then when you change your public key, all you have to do is to get the new key certified by the same CA as before, and then all your servers will automatically accept it without needing individual reconfiguration. |
| - | The GSSAPI is a generic API for doing client-server authentication. The | + | One way to use a certificate is to incorporate it into your private key file. You can [[ui_puttygen#certificate|do that using PuTTYgen]]. But another approach is to tell WinSCP itself where to find the public certificate file, and then it will automatically present that certificate when authenticating with the corresponding private key. |
| - | motivation behind it is that every security system has its own API, and the | + | |
| - | effort involved with adding different security systems to applications is | + | |
| - | extremely difficult with the variance between security APIs. However, with a | + | |
| - | common API, application vendors could use the generic API and it could | + | |
| - | work with any number of security platforms (Kerberos, Entrust, ...). | + | |
| - | The SSPI is Microsoft specific (non-standard) implementation of GSSAPI. | + | To do this, enter the pathname of the certificate file into the //Certificate to use with the private key// file selector. |
| - | To use MIT Kerberos authentication, you need to have [[&url(kerberosforwin)|MIT Kerberos for Windows]] installed. | + | When this setting is configured, WinSCP will honour it no matter whether the private key is found in a file, or loaded into Pageant.((&puttydoccite)) |
| - | If your Kerberos realm is not in the AD, MIT Kerberos authentication will not be used. For this you will need to specify a //[[ui_login_authentication#service_principal_name_sspi|Service Principal Name]]// as described below. Then, either store the password for ''<user>@<realm>'' by going to //Windows Start Menu > Settings > Control Panel > User Accounts > Advanced > Manage Passwords > Add// or use following command to start WinSCP: ((If the latter method is used, the credentials that get established at startup after providing the kerberos password are only available to children of the initial process)) | + | ===== [[gssapi]] GSSAPI ===== |
| - | runas /netonly /user:<user>@<realm> <path_to_winscp> | + | |
| - | When you want to use [[integration_app#putty|integration with PuTTY]], you may find Kerberos-enabled version of PuTTY useful. Such as [[&url(qputty)|Quest PuTTY]]. | + | ==== Attempt GSSAPI authentication ==== |
| - | ===== Allow agent forwarding ===== | + | The GSSAPI authentication is a mechanism which delegates the authentication exchange to a library elsewhere on the client machine, which in principle can authenticate in many different ways but in practice is usually used with the Kerberos single sign-on protocol to implement passwordless login. |
| - | This option allows the SSH server to open forwarded connections back to your local copy of Pageant. If you are not running Pageant, this option will do nothing. Learn more about [[&url(puttyagentfwd)|agent forwarding]]. ((&puttydoccite)) | + | WinSCP supports two forms of GSSAPI-based authentication. In one of them, the SSH key exchange happens in the normal way, and GSSAPI is only involved in authenticating the user. The checkbox labelled //Attempt GSSAPI authentication// controls this form. |
| - | ===== Service principal name (SSPI) ===== | + | In the other method, GSSAPI-based authentication is combined with the SSH key exchange phase. If this succeeds, then the SSH authentication step has nothing left to do. See the [[ui_login_kex#gssapi|//Attempt GSSAPI key exchange// checkbox]] on the //Key exchange// page. |
| - | The situation where this option is useful is where you do not have Kerberos for Windows on a local machine and are using cross realm where the realm of the server is not in AD. The local machine can be part of a domain, or a stand alone machine. It is proving handy for use from home for example. | + | |
| - | The //Service Principal Name// should be entered in the form: | + | If one or both of these controls is enabled, then GSSAPI authentication will be attempted in one form or the other, and (typically) if your client machine has valid Kerberos credentials loaded, then WinSCP should be able to authenticate automatically to servers that support Kerberos logins. |
| - | <code> | + | If both of those checkboxes are disabled, WinSCP will not try any form of GSSAPI at all, and the rest of the //GSSAPI// box is unused. |
| - | host/<hostname>@<realm> | + | |
| - | </code> | + | |
| - | When one of more of the realms are not in AD, then the Microsoft ''ksetup'' command will need to be used to define the realms to the local machine. It can be found on the Windows XP PRO CD under support tools which get installed into ''C:\Program Files\Support Tools\''. There is also a version for Windows 2000. | + | ==== [[gssapi_delegation]] Allow GSSAPI credential delegation ==== |
| + | %%GSSAPI%% credential delegation is a mechanism for passing on your Kerberos (or other) identity to the session on the SSH server. If you enable this option, then not only will WinSCP be able to log in automatically to a server that accepts your Kerberos credentials, but also you will be able to connect out from that server to other Kerberos-supporting services and use the same credentials just as automatically.· | ||
| - | <code> | + | This option is the Kerberos analogue of [[#forwarding|SSH agent forwarding]]. |
| - | ksetup /AddKdc <realm> <kdc_name> | + | |
| - | </code> | + | |
| - | (Repeat for other KDCs) | + | Note that, like %%SSH%% agent forwarding, there is a security implication in the use of this option: the administrator of the server you connect to, or anyone else who has cracked the administrator account on that server, could fake your identity when connecting to further Kerberos-supporting services. However, Kerberos sites are typically run by a central authority, so the administrator of one server is likely to already have access to the other services too; so this would typically be less of a risk than %%SSH%% agent forwarding. ((&puttydoccite)) |
| - | + | ||
| - | <code> | + | |
| - | ksetup /SetRealmFlags <realm>; TCPSupported Delegate | + | |
| - | </code> | + | |
| - | If the realm has the DNS SRV records setup the ''kdc_name'' is optional at least on XP. | + | ===== Further Reading ===== |
| - | MIT 1.3 KDCs supports TCP. The ''Delegate'' flag is needed for servers in the MIT realm as it does not return the ''OK_TO_DELEGATE'' flag. The ''Delegate'' flag is also needed to have an AFS token issued when the server is using the Andrew File System. | + | Read more about [[ui_login|Login dialog]] and [[ui_login_advanced|Advanced Site Settings dialog]]. |