OpenSSH Single sign-on

From SambaWiki
Jump to: navigation, search

This section explains how to allow passwordless SSH between Samba AD joined Linux hosts (or Passwordless SSH using Putty from Windows machines joined to the same domain).

Kerberos & Samba setup

This section assumes your joined machine's krb5.conf files (on the SSH server) are appropriately configured (usually this happens automatically when they are joined) and are set to point to a suitable krb5 keytab. This is generated by running "net ads keytab create" (on the joined machine), which will usually put this in a suitable place for kerberos to find, by default /etc/krb5.keytab. If not, you may need to add "default_keytab_name" entry in you krb5.conf to point to the generated /etc/krb5.keytab.

I have also required in smb.conf:

kerberos method = secrets and keytab
winbind refresh tickets = yes

and in /etc/security/pam_winbind.conf :

krb5_auth = yes
krb5_ccache_type = FILE

for the console based logins and SSH failback to password to generate a Kerberos TGT ticket (as in if the passwordless login fails due to not having a suitable ticket on the calling machine). This is essential if using things like NFSv4 with Kerberos Authentication.

SSH has to be able to map Kerberos user principal names to local POSIX usernames (as exported by winbind/NSS). Default winbind settings will break this because they add a domain prefix to the POSIX username: "SAMDOM\administrator", which does not match the principal name "Administrator@SAMDOM.EXAMPLE.COM". Default Heimdal/MIT Kerberos client settings will strip the realm, leaving "Administrator", but that still does not match the POSIX username. Possible solutions:

  • Recommended: Make a custom auth_to_local mapping in your krb5.conf. Integrate the following into your configuration
        auth_to_local = RULE:[1:SAMDOM\$1]
  • Not recommended: Set the winbind "winbind use default domain = yes" option in smb.conf. This removes the "SAMDOM\" prefix from POSIX usernames, and then default Kerberos mappings will probably work. However, the "winbind use default domain" is not recommended, as per smb.conf(5) manpage: "It can cause confusion about responsibilities for a user or group. In many situations it is not clear whether winbind or /etc/passwd should be seen as authoritative for a user, likewise for groups."
  • An enterprising developer could create localauth plug-ins for both MIT Kerberos and Heimdal Kerberos that integrates with winbind... Both libraries support plug-ins that can provide custom principal to local name mappings...

Notes on this:

  • You will need to customize the above rule if you don't have default winbind usernames. For example, if you have a custom "winbind separator" option specified you would need to change the delimiter.
  • RULE: mappings are currently (2016-05-18) only supported by MIT Kerberos, not by Heimdal. There is not currently any support in Heimdal for this. Fortunately, most Linux distributions seem to link OpenSSH against MIT Kerberos.
  • Kerberos principal names could have upper-case letters, and winbind converts all usernames to lowercase. In general this would be a problem since POSIX usernames are case sensitive and Windows clients will have a ticket with upper-case letters in the principal, but winbind seems to be case insensitive here (as demonstrated by logging in interactively with an upper-case username).
  • Note that if winbind for some reason were to mangle the username besides changing case, the user probably can't log in without a custom mapping provided via "auth_to_local_names" in krb5.conf.

Also on DNS, we require working forward and reverse entries for the SSH servers. See the Apache Single Sign-On section for how to achieve this. Alternatively, if reverse DNS on your network is broken, you can set the rdns option in your krb5.conf like so:

    rdns = false

This will disable reverse lookups on MIT Kerberos, which most Linux distributions seem to link OpenSSH with. Currently, Heimdal Kerberos does not do reverse lookups at all as far as I could tell from my research.

SSH server setup

In /etc/ssh/sshd_config ensure you have the following options set:

# GSSAPI options
GSSAPIAuthentication yes
GSSAPICleanupCredentials yes
GSSAPIKeyExchange yes                # If your version supports this
GSSAPIStoreCredentialsOnRekey yes    # If your version supports this

Then restart the sshd.

SSH client setup

For the client side, ensure you have the following set under an appropriate "Host" section in /etc/ssh/ssh_config:

Host *
       GSSAPIAuthentication yes
       GSSAPIKeyExchange yes         # If your version supports this
       GSSAPIRenewalForcesRekey yes  # If your version supports this
       GSSAPITrustDns yes
Host *
       # It's best to limit this option to only trusted hosts:
       GSSAPIDelegateCredentials yes

The options marked "If your version supports this" are provided in many distribution shipped versions of OpenSSH. The "KeyExchange" options allow host verification via GSSAPI. The "GSSAPIStoreCredentialsOnRekey" (server option) and "GSSAPIRenewalForcesRekey" (client options) allow a Kerberos renewal to propagate down existing SSH connections.

To also allow Putty SSH logins to be passwordless from a Windows machine joined to the same domain as your Linux host requires a reasonably up-to-date version of Putty. Then all that needs set for a particular session are: under the Connection -> SSH -> Auth -> GSSAPI, select "Attempt GSSAPI authentication (SSH-2 only)" and "Allow GSSAPI credential delegation". And under Connection -> Data, select "Use system username". This works by relying on Microsoft-provided GSSAPI that uses the Kerberos ticket acquired when you logged in.

When connecting, realize that principal names and SSH usernames must match. For example, the UPN showed by "klist" on the client must match the username given to SSH client. This is case sensitive.


It is desirable to set "Trust this computer for delegation to any service (Kerberos only)" under the "Delegation" tab in Users and Computers for the computer objects you are SSHing into. This allows your kerberos tickets to pass to the machine you are SSHing into. Through this you can use Kerberized services on the system you have SSH'd into, for example SSHing into yet another computer without a password.

(This tutorial was provided by Colin Simpson, and amended with more Kerberos details by James Johnston. Thanks.)