Configure SSH proxy and command logs
Cloudflare Zero Trust supports SSH proxying and command logging using Secure Web Gateway and the WARP client.
You can create network policies to manage and monitor SSH access to your applications. When a device connects to your origin server over SSH, a session log will be generated showing which user connected, the session duration, and optionally a full replay of all commands run during the session.
1. Ensure Unix usernames match user SSO identities
Cloudflare Gateway will take the identity from a token and, using short-lived certificates, authorize the user on the target infrastructure.
The simplest setup is one where a user’s Unix username matches their email address prefix. Issued short-lived certificates will be valid for the user’s email address prefix. For example, if a user in your Okta or GSuite organization is registered as
[email protected], they would log in to the SSH server as
For testing purposes, you can run the following command to generate a Unix user on the machine:
$ sudo adduser jdoe
Advanced setup: Differing usernames
SSH certificates include one or more
principals in their signature which indicate the Unix usernames the certificate is allowed to log in as. Cloudflare Access will always set the principal to the user’s email address prefix. For example, when
[email protected] tries to connect, Access issues a short-lived certificate authorized for the principal
By default, SSH servers authenticate the Unix username against the principals listed in the user’s certificate. You can configure your SSH server to accept principals that do not match the Unix username.
Username matches a different email
[email protected] to log in as the user
johndoe, add the following to the server’s
Match user johndoeAuthorizedPrincipalsCommand /bin/echo 'jdoe'AuthorizedPrincipalsCommandUser nobody
This tells the SSH server that, when someone tries to authenticate as the user
johndoe, check their certificate for the principal
jdoe. This would allow the user
[email protected] to sign into the server with a command such as:
$ ssh johndoe@server
Username matches multiple emails
To allow multiple email addresses to log in as
vmuser, add the following to the server’s
Match user vmuserAuthorizedPrincipalsFile /etc/ssh/vmusers-list.txt
This tells the SSH server to load a list of principles from a file. Then, in
/etc/ssh/vmusers-list.txt, list the email prefixes that can log in as
vmuser, one per line:
Username matches all users
To allow any Access user to log in as
vmuser, add the following command to the server’s
Match user vmuserAuthorizedPrincipalsCommand /bin/bash -c "echo '%t %k' | ssh-keygen -L -f - | grep -A1 Principals"AuthorizedPrincipalsCommandUser nobody
This command takes the certificate presented by the user and authorizes whatever principal is listed on it.
Allow all users
To allow any Access user to log in with any username, add the following to the server’s
AuthorizedPrincipalsCommand /bin/bash -c "echo '%t %k' | ssh-keygen -L -f - | grep -A1 Principals"AuthorizedPrincipalsCommandUser nobody
2. Generate a Gateway SSH proxy CA
Instead of traditional SSH keys, Gateway uses short-lived certificates to authenticate traffic between Cloudflare and your origin.
To generate a Gateway SSH proxy CA and get its public key:
- curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/access/gateway_ca"\-H "X-Auth-Email: <EMAIL>" \-H "X-Auth-Key: <API_KEY>"
A success response will include a
public_keyvalue. Save the key for configuring your server.
3. Save your public key
- Copy the
public_keyvalue returned by the API request in Step 2.
Use the following command to change directories to the SSH configuration directory on the remote target machine:$ cd /etc/ssh
Once there, you can use the following command to both generate the file and open a text editor to input/paste the public key.$ vim ca.pub
ca.pubfile, paste the public key without any modifications.
ca.pubfile can hold multiple keys, listed one per line. Empty lines and comments starting with
#are also allowed.
ca.pubfile. In some systems, you may need to use the following command to force the file to save depending on your permissions::w !sudo tee %:q!
4. Modify your SSHD config
The following procedure makes two changes to the
sshd_config file on the remote target machine. The first change requires that you uncomment a field already set in most default configurations; the second change adds a new field.
While staying within the
/etc/sshdirectory on the remote machine, open the
sshd_configfile.$ vim /etc/ssh/sshd_config
Go to the row named
PubkeyAuthentication. In most default configurations, the row will appear commented out as follows:# PubkeyAuthentication yes
Remove the # symbol to uncomment the line; keep the setting
Next, add a new line below
PubkeyAuthenticationas follows:TrustedUserCAKeys /etc/ssh/ca.pub
Save the file and quit the editor. You might need to use the following command again to save and exit.:w !sudo tee %:q!
5. Check your SSH port number
Cloudflare’s SSH proxy only works with servers running on the default port 22. Open the
sshd_config file and verify that no other
Port values are specified.
$ cat /etc/ssh/sshd_config
6. Restart your SSH server
Once you have modified your SSHD configuration, restart the SSH service on the remote machine.
For older Debian/Ubuntu versions:
$ sudo service ssh restart
For newer Debian/Ubuntu versions:
$ sudo systemctl restart ssh
For CentOS/RHEL 6 and older:
$ sudo service sshd restart
For CentOS/RHEL 7 and newer:
$ sudo systemctl restart sshd
7. Create an Audit SSH policy
In the Network tab, create a new network policy.
Add any other conditions to your policy. If a user does not meet the criteria, they will be blocked by default.
In the Action dropdown, select Audit SSH.
Save the policy.
8. Connect as a user
Users can use any SSH client to connect to the target resource, as long as they are logged into the WARP client on their device. Cloudflare Zero Trust will authenticate, proxy, and optionally encrypt and record all SSH traffic through Gateway.
Users must specify their desired username to connect with as part of the SSH command:
$ ssh <username>@<hostname>
(Optional) Configure SSH Command Logging
ssh-log-cliutility, generate a public and private key pair.$ ./ssh-log-cli generate-key-pair -o sshkey$ lsREADME.md ssh-log-cli sshkey sshkey.pub
This command outputs two files, an
sshkey.pubpublic key and a matching
In the SSH encryption public key field, paste the contents of
sshkey.puband select Save. Note that this a different public key from the
ca.pubfile you used to configure the origin server.
View SSH Logs
In Zero Trust, go to Logs > Gateway > SSH.
If you enabled the SSH Command Logging feature, you can Download a session’s command log.
- $ ./ssh-log-cli decrypt -i sshlog -k sshkey
This command outputs a
sshlog-decrypted.zipfile with the decrypted logs.