How to customize your SSH client

You can establish connexions to the hosts in CCIN2P3 Login Farm by using the password associated to your individual account. This method implies that you need to type in your password every time you connect to the login farm.

Alternatively, you can establish secure, passwordless connexions to the login farm provided that you:

install and configure Kerberos on your personnal computer, and
configure your SSH client to use Kerberos tickets (instead of your password)

When done, you will only need to type your password periodically (typically once per day) and then you can establish as many secure connexions as you need for your work.

In this tutorial you can find details on how to install Kerberos and configure your SSH client on your personal computer, a one time process.

Step 1: install and configure Kerberos

Kerberos is a network authentication protocol that allows you to prove your identity to the hosts in the login farm in a secure manner by using SSH. If not already done, you can install Keberos on your computer:

Ubuntu: sudo apt-get update && sudo apt-get install krb5-config krb5-user krb5-doc
CentOS: sudo yum install krb5-workstation
Fedora: sudo dnf install krb5-workstation. You may also use sudo yum install krb5-workstation if you don’t have dnf installed on your computer.
macOS: Kerberos is included in macOS, you have nothing to do.

After installing Kerberos, you can use commands such as kinit(1), klist(1), krenew(1) and kdestroy(1). These commands require that the file /etc/krb5.conf exists and is correctly configured. The default contents of /etc/krb5.conf is likely not suitable for our purposes, so you can freely rename it and use your preferred editor to populate that file with the contents below, which is valid for both macOS and Linux:

[libdefaults]
    default_realm       = CC.IN2P3.FR
    dns_lookup_realm    = false
    dns_lookup_kdc      = true
    allow_weak_crypto   = false
    kdc_timeout         = 10
    max_retries         = 3
    ticket_lifetime     = 3d
    renew_lifetime      = 30d
    forwardable         = true
    proxiable           = false
    default_ccache_name = DIR:/tmp/kerberos

[realms]
    CC.IN2P3.FR = {
        default_domain  = idm.cc.in2p3.fr
        kpasswd_server  = ccidm01.in2p3.fr
        admin_server    = ccidm01.in2p3.fr
        kdc             = ccidm01.in2p3.fr:88
        kdc             = ccidm02.in2p3.fr:88
        kdc             = ccidm03.in2p3.fr:88
        kdc             = ccidm04.in2p3.fr:88
    }

[appdefaults]
    encrypt = true

Note

You can use another location for the Kerberos configuration file (e.g. $HOME/krb5.conf) by initializing the environment variable KRB5_CONFIG with the path to your file (e.g. export KRB5_CONFIG=$HOME/krb5.conf). This alternative way may be useful if you don’t have super-user privileges on the computer you use to connect to CC-IN2P3 login farm to be able to to modify the file /etc/krb5.conf.

You should now be able to obtain a Kerberos ticket. Assuming your user name at CC-IN2P3 is lsstuser, do:

$ kinit lsstuser@CC.IN2P3.FR
Password for lsstuser@CC.IN2P3.FR: •••••••••••

and type in the password associated to the account lsstuser at CC-IN2P3.

Important

Kerberos is case-sensitive so you must type the realm CC.IN2P3.FR in upper case.

You can verify that you successfully obtained a ticket using the klist command:

$ klist
Ticket cache: DIR::/tmp/kerberos/tkt
Default principal: lsstuser@CC.IN2P3.FR

Valid starting       Expires              Service principal
07/24/2019 14:47:02  07/25/2019 14:47:02  krbtgt/CC.IN2P3.FR@CC.IN2P3.FR
        renew until 07/31/2019 14:47:02

The output of klist shows that you have successfully obtained a Kerberos ticket which is cached in your personal computer and also shows the ticket’s validity period. CC-IN2P3’s Kerberos delivers tickets with a maximum validity period of 3 days. However, you can obtain a Kerberos ticket with a shorter duration if you so wish (see -l option of kinit).

Note

If your user name on your personnal computer is the same as your user name at CC-IN2P3 (e.g. lsstuser) and you only have configured Kerberos for the realm CC.IN2P3.FR, you can acquire a ticket by typing kinit without arguments. The Kerberos ticket’s principal (i.e. lsstuser@CC.IN2P3.FR) is inferred from the user name of the current session and the default realm from the configuration file /etc/krb5.conf.

Step 2: configure your SSH client to use Kerberos

In the previous step you have proven your identity by obtaining a Kerberos ticket via the kinit command. You can now connect via SSH to CC-IN2P3 login farm without typing your password again, as many times as you need as long as your Kerberos ticket is still valid.

A convenient way to tell SSH that you want to use your Kerberos ticket rather than your password to connect to CC-IN2P3 login farm is to create an entry in your SSH configuration file in your personal computer (typically $HOME/.ssh/config) as shown below:

Ubuntu, CentOS, Fedora

Host cc
   Hostname                   cca.in2p3.fr
   User                       lsstuser
   GSSAPIClientIdentity       lsstuser@CC.IN2P3.FR
   GSSAPIAuthentication       yes
   GSSAPIDelegateCredentials  yes
   GSSAPITrustDns             yes

macOS

The SSH client shipped with macOS v10.12 and later does not include support for using Kerberos for connecting to a host behind a DNS alias, such as cca.in2p3.fr. You need to use a specific host name, such as cca001.in2p3.fr, which means that you will always connect to the same host. To mitigate this you may want to add several entries to $HOME/.ssh/config, each one using a different host name:

Host cc
   Hostname                  cca001.in2p3.fr
   User                      lsstuser
   GSSAPIAuthentication      yes
   GSSAPIDelegateCredentials yes

In addition, if you have active Kerberos tickets for more than one realm, the macOS SSH client will use the ticket in the default credential cache, which may not be the one for CC.IN2P3.FR. To make sure your ticket for the reaml CC.IN2P3.FR is the default one, use the command:

$ kswitch -p lsstuser@CC.IN2P3.FR

before establishing the SSH connection. (Replace lsstuser above by your own login name at CC-IN2P3.)

After configuring your SSH client, you can securely connect to the login farm using your valid Kerberos ticket without being prompted for your password, by using the command:

ssh cc

Note

In this example we used cc in the line Host cc as a convenient short alias for naming CC-IN2P3 login farm. You may choose another alias which you find convenient for you.

Warning

Please bear in mind that CC-IN2P3 provides this passwordless connection mechanism for your own convenience. Anyone with physical access to your personnal computer may exploit this mechanism to connect to CC-IN2P3 login farm on your behalf.

Therefore, you are asked to take appropriate security measures to protect your individual credentials and personal computer from unauthorized access to avoid impersonation. The charter of good practice for using CC-IN2P3 services applies.

Step 3 (optional): advanced configuration

If you connect via SSH to several hosts at CC-IN2P3, you can specify them all in the file $HOME/.ssh/config. For instance on a Linux computer you can use:

Host cca
   Hostname cca.in2p3.fr

Host cca1
   Hostname cca001.in2p3.fr

Host cca8
   Hostname cca008.in2p3.fr

#
# The SSH options below apply to all 'Host' entries that match the pattern cc*
#
Host cc*
   User                      lsstuser
   GSSAPIClientIdentity      lsstuser@CC.IN2P3.FR
   GSSAPIAuthentication      yes
   GSSAPIDelegateCredentials yes
   GSSAPITrustDns            yes

More detailed information about customizing your SSH client can be found in the man page ssh_config(5) and in this tutorial .

In addition, it is also possible to configure Kerberos to acquire tickets for connecting to other sites you have an account for, provided they support passwordless connections. That is the case of sites such as CERN.CH or SLAC.STANFORD.EDU. If you need assistance to do configuration, please ask via the Slack channel #in2p3.

Troubleshooting your configuration

If you experience problems making this work for you, here are some tips which may help you debug the issues.

Make sure your personal computer can establish a TCP network connection to the Kerberos servers at CC-IN2P3, namely ccidm0{1,2,3,4}.in2p3.fr on port 88. Depending on your location (e.g. hotel, conference venue, etc.), outbound network connections to that port may be blocked. You can use the nc utility to check connectivity, for instance:

$ nc -v ccidm01.in2p3.fr 88
Ncat: Version 7.50 ( https://nmap.org/ncat )
Ncat: Connected to 134.158.104.46:88.
^C

If the test above fails, it is very likely that your personnal computer cannot connect to the Kerberos hosts at CC-IN2P3 from your current location, so the kinit command will not work. You can still connect to CC-IN2P3 login farm by typing your password.

Another possible cause of trouble is the permissions of the directory on your personal computer where kinit stores valid credentials. That directory is specified in the file /etc/krb5.conf, entry default_ccache_name and in we recommend it to be /tmp/kerberos (see Step 1: install and configure Kerberos). If you encounter an issue such as:

$ kinit lsstuser@CC.IN2P3.FR
kinit: Credentials cache I/O operation failed XXX while getting default ccache

you can freely remove the cache directory /tmp/kerberos and do kinit again: that directory will be automatically recreated when needed, with the appropriate permissions.