Configure short-lived certificates
Cloudflare Access can replace traditional SSH key models with short-lived certificates issued to your users based on the token generated by their Access login. In traditional models, users generate a keypair and commit their public key into an infrastructure management tool, like Salt, or otherwise upload it to an administrator. These keys can remain unchanged for months or years.
Cloudflare Access removes the burden on the end user of generating a key, while also improving security of access to infrastructure with ephemeral certificates.
1. Secure a server behind Cloudflare Access
Cloudflare Access short-lived certificates can work with any modern SSH server, whether it is behind Access or not. However, we recommend putting your server behind Access for added security and features, such as auditability and browser-based terminals.
To secure your server behind Cloudflare Access, follow these instructions.
2. Ensure Unix usernames match user SSO identities
Cloudflare Access 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 jdoe@example.com
, they would log in to the SSH server as jdoe
.
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 jdoe@example.com
tries to connect, Access issues a short-lived certificate authorized for the principal jdoe
.
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
To allow jdoe@example.com
to log in as the user johndoe
, add the following to the server’s /etc/ssh/sshd_config
:
Match user johndoe AuthorizedPrincipalsCommand /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 jdoe@example.com
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 /etc/ssh/sshd_config
:
Match user vmuser AuthorizedPrincipalsFile /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:
jdoebwaynerobin
Username matches all users
To allow any Access user to log in as vmuser
, add the following command to the server’s /etc/ssh/sshd_config
:
Match user vmuser AuthorizedPrincipalsCommand /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 /etc/ssh/sshd_config
:
AuthorizedPrincipalsCommand /bin/bash -c "echo '%t %k' | ssh-keygen -L -f - | grep -A1 Principals"AuthorizedPrincipalsCommandUser nobody
Since this will put the security of your server entirely dependent on your Access configuration, make sure your Access policies are correctly configured.
3. Generate a short-lived certificate public key
In Zero Trust, navigate to Access > Service Auth.
In the dropdown, choose the application that represents the resource you secured in Step 1.
Click Generate certificate. A row will appear with a public key scoped to your application.
Save the key or keep it somewhere convenient for configuring your server. You can return to copy this public key any time in the Service Auth dashboard.
4. Save your public key
- Copy the public key generated from the dashboard in Step 2.
Use the following command to change directories to the SSH configuration directory on the remote target machine:
$ cd /etc/sshOnce 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.pubIn the
ca.pub
file, paste the public key without any modifications.The
ca.pub
file can hold multiple keys, listed one per line. Empty lines and comments starting with#
are also allowed.Save the
ca.pub
file. 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!
5. 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/ssh
directory on the remote machine, open thesshd_config
file.$ vim /etc/ssh/sshd_configNavigate to the row named
PubkeyAuthentication
. In most default configurations, the row will appear commented out as follows:# PubkeyAuthentication yesRemove the # symbol to uncomment the line; keep the setting
yes
enabled.Next, add a new line below
PubkeyAuthentication
as follows:TrustedUserCAKeys /etc/ssh/ca.pubSave the file and quit the editor. You might need to use the following command again to save and exit.
:w !sudo tee %:q!
6. Restart your SSH server
Once you have modified your SSHD configuration, restart the SSH service on the remote machine.
Debian/Ubuntu
For older Debian/Ubuntu versions:
$ sudo service ssh restart
For newer Debian/Ubuntu versions:
$ sudo systemctl restart ssh
CentOS/RHEL
For CentOS/RHEL 6 and older:
$ sudo service sshd restart
For CentOS/RHEL 7 and newer:
$ sudo systemctl restart sshd
7. Connect as a user
Configure your client SSH config
On the client side, configure your device to use Cloudflare Access to reach the protected machine. To use short-lived certificates, you must include the following settings in your SSH config file (~/.ssh/config
).
To save time, you can use the following cloudflared command to print the required configuration command:
$ cloudflared access ssh-config --hostname vm.example.com --short-lived-cert
If you prefer to configure manually, this is an example of the generated SSH config:
Match host vm.example.com exec "/usr/local/bin/cloudflared access ssh-gen --hostname %h" HostName vm.example.com ProxyCommand /usr/local/bin/cloudflared access ssh --hostname %h IdentityFile ~/.cloudflared/vm.example.com-cf_key CertificateFile ~/.cloudflared/vm.example.com-cf_key-cert.pub
Connect through a browser-based terminal
End users can connect to the SSH session without any configuration by using Cloudflare’s browser-based terminal. Users visit the URL of the application and Cloudflare’s terminal handles the short-lived certificate flow. To enable, follow the instructions here.
Your SSH server is now protected behind Cloudflare Access — users will be prompted to authenticate with your identity provider before they can connect. You can also enable SSH command logging by configuring a Gateway Audit SSH policy.