Quest's GSSAPI-enabled PuTTY - a quick guide
- About Quest PuTTY
- The importance of Service Principal Names
- How PuTTY determines the SPN from the hostname
- Overriding the SPN
- Checking the SPN
About Quest PuTTY
The Quest PuTTY Secure SHell (SSH) client provided by Resource Central is based on the popular Windows based client by Simon Tatham. Quest have extended PuTTY's capabilities to include GSSAPI-with-MIC (Message Integrity Check) based user authentication, enabling secure, enterprise single sign-on. Full documentation of the PuTTY-based tools is found at the upstream project web site. These notes describe the Quest extended features only.
The SSH protocol can achieve single sign-on with Active Directory
by using GSSAPI and the Kerberos protocol.
Kerberos uses cryptographically-secure
tickets obtained from a
trusted source called the Key Distribution Center (KDC),
normally obtained from a Windows domain controller by
the workstation when the user logs in.
Tickets obtained during the SSH connection reveal the
username to the server in a secure way.
Quest PuTTY uses Microsoft's Security Service Provider Interface (SSPI), which is Microsoft's version of the GSSAPI, with which it is wire compatible. SSPI takes care of obtaining Kerberos tickets from Active Directory. When Quest Authentication Services (QAS) is used on the remote unix host, it can be joined to the same Active Directory domain as the Windows client. A GSSAPI-with-mic enabled SSH server process running on the remote host can examine the ticket and authenticate the user without needing to prompt for a password.
The Windows user running Quest PuTTY must first have a valid unix user on the target system. Quest PuTTY, by default, assumes the username to use on the target system is the same as the Windows logon name. This can be changed in the auto-login username field, as shown in Figure 1.
Figure 1: Changing the Auto-login username field
The importance of Service Principal Names
Host authentication relies heavily on getting the Service Principal Name right. A Service Principal Name ("SPN") is the unique name given to a security entity by Kerberos/Active Directory. The SPN used by the client must match exactly that given to the server, or authentication will not succeed.
Service Principal Names take the form of: service/hostname@REALM where
- service is the service type
hostfor login services),
- hostname is the fully qualified host name
- REALM is the Active Directory domain
How PuTTY determines the SPN from the hostname
Quest PuTTY normally deduces the server's SPN from the hostname entered in the session configuration (shown in Figure 2).
This is how it works:
- PuTTY attempts to determine whether the hostname entered is an IP address. If it looks like one, and the Trust DNS checkbox is enabled, it will try a 'reverse DNS lookup' to get the hostname. If the reverse lookup is not successful, no SSPI-based connection will be attempted.
- PuTTY checks to see if the hostname contains a
character. If it doesn't, and Trust DNS is enabled, then it uses the system's gethostbyname() call in an attempting to retrieve the fully qualified host name from DNS.
- Finally, PuTTY prepends the hostname with
host/to form the SPN. Note that no realm is appended: it is left to the SSPI (Windows) to automatically append the current domain to form a complete SPN.
Complete details on how SPNs are determined are documented in the Quest PuTTY User Manual (F.5 Determining Kerberos service prinicpal names).
Figure 2: Specifying the target host name
Overriding the SPN
The Service Principal Name isn't always deduced correctly by PuTTY. This can happen when
- the target host is in a different domain
- DNS is not working, or is misconfigured
- the host was joined with a completely different name
- there are case mismatches with external KDCs
In these cases, the target SPN can be specified directly during configuration. Figure 3 shows where this field is located.
Figure 3: Overiding the deduced SPN with an explicit principal name
Checking the SPN
When attempting the connection to the target system, PuTTY will display the SPN that it decided to use (See figure 4). If the connection is not successful, look closely at the SPN. This string can be used as a starting point for specifying the correct one in the override field.
Figure 4: PuTTY reporting the authenticated SPN of the remote server
Quest PuTTY comes with a command-line sister executable called PuTTY Link, invoked as Plink. Plink is a console version of PuTTY and allows most PuTTY options to be specified on the command line.
The installer places the plink.exe program (as well as pscp.exe) in the folder Program Files\Quest Software\PuTTY. The path to these tools is added to the system's PATH environment variable by the installer, or it can be manually added through the "Advanced" tab on the "My Computer" Properties display.
Plink is a console application, which means it requires a console window to run. If plink is being used for automation, this may cause unwanted 'flashing' of black console windows. A separate program, plinkw is provided that has no console output. Plinkw is identical to plink, except that there is no console window created for output.
Figure 5 shows plink's options. Plink is convenient for running X-Windows based executables from the target system.
PuTTY, plink and plinkw are capable of tunneling X traffic through the encypted SSH connection. This enables X-based applications to display on the client machine, when an X-Server such as XFree86 is running on it.
Plink command line options
Quest PuTTY has added a few more command line parameters to plink for convenience, and are listed below. Summary help on these and other commands can be obtained by running plink without arguments, as shown in Figure 5.
- The -ng option disables all GSSAPI extensions.
- The -f option flags the Kerberos ticket as forwardable.
- The -k spn option can be used to specify the target Service Principal Name.
- The -use_vintela_gui_w_pwd option will prompt for all PuTTY-based input in a dialog box rather than from the command window.
- The -use_vintela_gui_no_pwd option will prompt for all input in dialogs except for the password.
- The -hide_console option is useful when calling X-Windows based applications as it will cause the created Command Prompt window to be hidden.
- The -auto_store_key_in_cache switch will bypass the
Store key in cachedialog, saving it automatically.
Please see the user manual (Appendix F.2: Extended options) for more options, and details.
Figure 5: Running plink to show the usage message
An example of using the SSPI-based plink on the command line is shown in Figure 6
plink -X -ssh willy-wagtail /usr/X11R6/bin/xterm
Figure 6: Plink example
PuTTY's scp clone, pscp, is also SSPI enabled. Like plink, when pscp is invoked, it attempts Kerberos authentication. An example of the pscp command line is shown in Figure 7.
pscp alice@targetmachine:/home/alice/filename .
Figure 7: pscp example, copying a remote file to . (the current directory)
This section contains some tips on solving authentication problems when using PuTTY.
- If authentication isn't working as you expect, examine the Event Log found in the menu under the PuTTY icon in the very top left corner of the terminal window.
- Even more detail can be obtained by enabling logging through the Logging configuration panel.
- Ask your administrator to examine the SSH server logs on the target host to see if an explanation has been recorded there.
- If the target host has recently been rejoined to the domain, the service key may have changed and your credential cache may contain stale entries. Try locking and unlocking your windows session: Ctrl-Alt-Del; Lock Computer; Unlock computer. Entering your password to unlock the display causes the local session ticket cache to be reloaded.
Internal Error 2755
When installing PuTTY inside a Terminal Server session, you may encounter the error Internal Error 2755. Please see KB 254841. The workaround is to copy the installer file to a local drive and install from there.
Trouble delegating credentials
For credential forwarding (also known as delegation) to work from a Windows client to an SSH server, the conditions in KB 283201 must be met. You can also verify the delegation flag is set in the client's acquired service ticket by using the kerbtray tool.
Logging for bug reports
Bug reports are welcome through our bug system. Before sending a bug report, please make note of the version of Quest PuTTY you are using. It can also be helpful if you turn on full logging in the configuration panel and attach as much information to report as possible.