☰
Navigation :

Setting up SSH on MacOS

Using SSH on MacOS

DUO MultiFactor Authentication Required

Beginning August 5th 2025 ssh access to CSAIL systems requires DUO MultiFactor Authentication (MFA)

This uses the same app as MIT DUO so most people will already have that installed and set up. If you do not now is a good time to review their Knowledge Base article.

While we are using the same application (and under their license) CSAIL has a separate DUO instance with separate configuration.

Signing up for CSAIL DUO

Sign in to https://duo.csail.mit.edu/ and configure your preferences.

If you attempt to ssh to systems require DUO before this is configured you will be denied access and presented with a link to configure your DUO preferences:

$ ssh user@login.csail.mit.edu
user@login.csail.mit.edu's password:
Please enroll at https://api-f9e5e8b6.duosecurity.com/frame/portal/v4/enroll?code=1fc14591696012e7&akey=DAY2HO8ZVB7D9PBIZINN
Please enroll at https://api-f9e5e8b6.duosecurity.com/frame/portal/v4/enroll?code=1fc14591696012e7&akey=DAY2HO8ZVB7D9PBIZINN
Please enroll at https://api-f9e5e8b6.duosecurity.com/frame/portal/v4/enroll?code=1fc14591696012e7&akey=DAY2HO8ZVB7D9PBIZINN
user@login.csail.mit.edu: Permission denied (publickey,gssapi-with-mic,keyboard-interactive).

That time limited link will also allow you to configure your DUO settings (and yes it is normal to see it 3x)

Minimizing Second Factor Prompts

The recommended CSAIL jump host configuration uses SSH Multiplexing such that you will only be prompted for DUO authentication when you first connect. So long as you maintain an open ssh session through the jump host DUO will not be required for subsequent connections through the jump hosts, even if they are to different endpoint hosts. After 30min with no open connections the multiplexing socket will time out and on the next connection you’ll again get a DUO prompt.

Dealing with “problem” clients and workflows

IDEs (VScode, Cursor, PuTTY, etc) and other interactive tools that use SSH

Many integrated development environments (IDE’s) and other tools that use SSH behind the scenes provide poor or no UI to deal with entering a second factor. If you follow the Minimizing Second Factor Prompts instructions above and manually ssh to any CSAIL host before using the problematic tool it won’t need a second factor to connect and everything should function noramally.

Automated non-interactive processes

TIG can create configuration exceptions for internal cluster communications and exceptions for limited scope system accounts using SSHKey authentication. This is not self-service and requires a security review and custom configuration.

Please contact help@csail.mit.edu to arrange for custom configuration and testing as soon as possible to ensure a smooth transition

SSH access restrictions

Inbound SSH connections from outside the CSAIL network to most systems on the CSAIL network are blocked by default. SSH connections within the CSAIL network (either on Ethernet or CSAILPrivate) remain open. Inbound SSH connections to the public login server login.csail.mit.edu remain open.

To SSH to systems from outside the CSAIL network it is strongly recommended that you Use the CSAIL jump host for SSH access as this by passes the firewall restriction and Minimizes DUO Prompts

It is also possible to bypass the firewall restriction using:

  1. Campus VPN
  2. Allowlist an SSH server

If the system you are connecting to inside the CSAIL is not running CSAIL Linux these methods are fine, however if you are connecting to a CSAIL Linux using one of these methods rather than the jump-host method will require DUO interaction on every ssh connection which is not a good experience.

Using SSH with the CSAIL Jump Host

TIG is supplying a dedicated jump host (separate from the login servers) called jump.csail.mit.edu. This server is configured to allow only proxy connections, not interactive logins.

Connections through the jump host are multiplexed using ControlSockets so only the initial connection will require DUO interaction and internal hosts are configured to allow Single Factor when coming from the jumphost since the Second Factor has arleardy been enforced there. The GREATLY reduces the burden of re-authenticating and allow and easy way for problem clients to avoid issues by piggy backing on existing strongly authenticated connections

Despite the network restrictions most people can continue to transparently access all CSAIL systems by setting up their client ssh config.

Configuring CSAIL SSH via Jump Host for Mac OS 14+

Two Steps are required

  1. Place the following in the .ssh/config file within your local home directory (ie, /Users/$YOU/.ssh/config).
  2. Create the directory ~/.ssh/cm_socket either through the Finder or by opening a terminal and running mkdir ~/.ssh/cm_socket

This configuration will use allow you to SSH to systems from within or outside the CSAIL network using Kerberos authentication and minimizing DUO prompts.

HashKnownHosts yes
VerifyHostKeyDNS ask
CanonicalizeHostname always
CanonicalDomains csail.mit.edu

# all  CSAIL hosts use GSSAPI
Host *.csail.mit.edu 128.52.* 128.30.*
  GSSAPIAuthentication yes
  # If you have a different local username uncomment the following line
  # and fill in your CSAIL UserName
  # User <CSAIL UserName>

# jumps reuse existing connections to minimize DUO prompting
# "ControlPath" must exist and cannot be in AFS
#
# NOTE: if you are on a laptop or other systems that switches 
# networks the Control Socket will need to be manually removed
# in order for it to get recreated on the new network:
#
# rm ~/.ssh/cm_socket/*
#
# The symptom is new ssh session hanging prior to connection
# It is always safe to run this command though it will require 
# Duo auth on re-establish the connection.

Host jump.csail.mit.edu

  ControlMaster auto
  ControlPersist 1800

  ### This directory must be manually created! ###
  ControlPath ~/.ssh/cm_socket/%C


# CSAIL hosts except jumphosts get GSSAPIDelegateCredentials for AFS
Host *.csail.mit.edu   !jump.csail.mit.edu 128.52.* 128.30.* 128.31.*
  ProxyJump jump.csail.mit.edu
  GSSAPIDelegateCredentials yes
  ForwardAgent yes

# if you ssh to ATHENA systems
# uncomment the lines below
# and edit to include your ATHENA Username
#Host !*.csail.mit.edu *.mit.edu
#  User <ATHENA UserName>
#  GSSAPIAuthentication yes
#  GSSAPIDelegateCredentials yes

The above will allow you to connect to hosts using their fully qualified domain names (eg, ssh login.csail.mit.edu). or their short names (login). If you want to also use X11 (to run extra xterms or MATLAB remotely, for example), make sure XQuartz is installed on your Mac and then uncomment ForwardX11 yes.

Once you save the file, make sure that you are its owner and no one else can write to it. For example:

$ chmod 600 config
$ chown $YOU config