step-ssh-ctl uses mTLS to talk to Smallstep's API server—which complicates its use behind a proxy server. It authenticates to the server using the host identity certificate in /root/.step/identity.
Both step-ssh-ctl and step accept the HTTPS_PROXY environment variable. However, the proxy (outer) TLS connection will not use your system's trust store. Our tools only trust what you explicitly tell it to trust. So, to get step-ssh-ctl and step to trust your proxy server, you may need to append your proxy's root certificate PEM block to /root/.step/certs/root_ca.crt.
Enrolling a host from behind a proxy
To enroll hosts behind a proxy server, setting an HTTPS_PROXY when running step-ssh and step-ssh-ctl should work. So, you can run the [ssh-host.sh](<http://ssh-host.sh>) setup script like this:
HTTPS_PROXY=https://proxy.url bash ssh-host.sh
Configuring a host for ongoing use behind a proxy
To configure a host for ongoing use of Smallstep SSH from behind a proxy server, you'll need to change the following files to add the HTTPS_PROXY environment variable:
Add Environment=HTTPS_PROXY=https://your.proxy.tld to the following systemd service units:
/etc/systemd/system/step-ssh-renew.service/etc/systemd/system/step-ssh-metadata.service
In the PAM configuration files /etc/pam.d/sshd and /etc/pam.d/sudo files, change the step-ssh-ctl line from:
session optional pam_exec.so /usr/bin/step-ssh-ctl session
to:
session optional pam_exec.so /bin/env bash -c 'export HTTPS_PROXY=https://proxy.url; /usr/bin/step-ssh-ctl session'
You can test the proxy by running the following as root:
HTTPS_PROXY=https://proxy.url PAM_USER=alice PAM_TYPE=close_session step-ssh-ctl session