Zoey/ssh-short-lived

content/cloudflare-one/_partials/_ssh-restart-server.md

@@ -10,13 +10,19 @@ Once you have modified your SSHD configuration, you still need to restart the SS
 ### Debian/Ubuntu
 
   ```sh
+  # For older Debian/Ubuntu versions:
   $ sudo service ssh restart
+
+  # For newer Debian/Ubuntu versions:
   $ sudo systemctl restart ssh
   ```
 
 ### CentOS/RHEL
 
   ```sh
+  # For CentOS/RHEL 6 and older:
   $ sudo service sshd restart
+
+  # For CentOS/RHEL 7 and newer:
   $ sudo systemctl restart sshd
   ```

content/cloudflare-one/_partials/_ssh-usernames.md

@@ -5,12 +5,87 @@ _build:
   list: never
 ---
 
-In order to match a user to their SSO identity, the user's Unix username must match their email address prefix. For example, `jdoe` must be registered in your Okta or GSuite organization as `jdoe@example.com`.
-
-You can create a user entry with duplicate `uid`, `gid`, and home directory to link an identity to an existing user with a different username. You will need to create a password for it separately and add it to the same groups to replicate permissions.
+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 user `jdoe@example.com` connects to `vm.example.com`, they would try to sign in as the user `jdoe`.
 
 For testing purposes, you can run the following command to generate a Unix user on the machine:
 
 ```sh
 $ sudo adduser jdoe
 ```
+
+<details>
+<summary>Advanced Setup: Differing usernames</summary>
+<div>
+
+SSH certificates have no concept of username, and instead authorize users to a "principal".
+When `jdoe@example.com` tries to connect to `vm.example.com`, the short-lived certificate is authorized for the principal `jdoe`.
+
+By default, an SSH server will authenticate the username against the list of principals in the user's cert.
+However, you can override this behavior by instead offering a command to say which principals are authorized.
+
+If you'd like to allow `jdoe@example.com` to log in as the user `johndoe`, you can add the following to the server's `/etc/ssh/sshd_config`:
+```sh
+Match user 'johndoe'
+  AuthorizedPrincipalsCommand 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`.
+
+If you'd like to authorize multiple users, replace the `AuthorizedPrincipalsCommand` above with one to echo multiple usernames, separated by `\n`.
+For example, to allow `jdoe@example.com` and `bwayne@example.com` to both log in as `vmuser`:
+
+```sh
+Match user 'vmuser'
+  AuthorizedPrincipalsCommand echo -e 'jdoe\nbwayne'
+  AuthorizedPrincipalsCommandUser nobody
+```
+
+Alternatively, you can specify a list of principals (in this case, usernames from users' emails) in a file, and pass that to ssh instead:
+
+```sh
+Match user 'vmuser'
+  AuthorizedPrincipalsFile /etc/ssh/vmusers-list.txt
+```
+
+Then, in `/etc/ssh/vmusers-list.txt`, list the users that can sign in as `vmuser`, one per line:
+
+```text
+jdoe
+bwayne
+robin
+```
+
+For any of these configs you'll also need the `TrustedUserCAKeys` option, as documented below.
+</div>
+</details>
+
+<details>
+<summary>Advanced Setup: Allowing any user to log in</summary>
+<div>
+
+If you'd like to allow any user to log in as a particular user, you can add the following command to the server's `/etc/ssh/sshd_config`:
+
+```sh
+Match user 'vmuser'
+  AuthorizedPrincipalsCommand bash -c "echo '%t %k' | ssh-keygen -L -f - | grep -A1 Principals"
+  AuthorizedPrincipalsCommandUser nobody
+```
+
+(there's no way to tell sshd to allow any verified certificate, so this takes the certificate presented by the user and authorizes whatever principal is listed on it)
+
+Or, to allow any Access user to log in as any user:
+
+```sh
+AuthorizedPrincipalsCommand bash -c "echo '%t %k' | ssh-keygen -L -f - | grep -A1 Principals"
+AuthorizedPrincipalsCommandUser nobody
+```
+
+(the same options, but without the `Match` block above it)
+
+This will put the security of your server entirely dependent on your Access configuration, so make extra sure your [access policies](/cloudflare-one/policies/access/policy-management/) are correctly configured.
+
+For any of these configs you'll also need the `TrustedUserCAKeys` option, as documented below.
+</div>
+</details>

content/cloudflare-one/identity/users/short-lived-certificates.md

@@ -16,6 +16,13 @@ Cloudflare Access removes the burden on the end user of generating a key, while
 
 To protect a resource behind Cloudflare Access, first follow [these instructions](/cloudflare-one/connections/connect-apps/use_cases/ssh/) to secure the server.
 
+{{<Aside type="note">}}
+
+Cloudflare Access short lived certificates can work with any modern SSH server, whether it's behind Access or not.
+However, we recommend putting your server behind Access for added security and features, such as auditability and browser-based terminals.
+
+{{</Aside>}}
+
 ## 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.
@@ -55,23 +62,18 @@ Cloudflare Access will take the identity from a token and, using short-lived cer
 
 ### Configure your client SSH config
 
-On the client side, follow [this tutorial](/cloudflare-one/connections/connect-apps/use_cases/ssh/) to 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.
+On the client side, follow [this tutorial](/cloudflare-one/connections/connect-apps/use_cases/ssh/) to 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:
 
 ```sh
 cloudflared access ssh-config --hostname vm.example.com --short-lived-cert
 ```
 
-If you prefer to configure manually, these are the required commands:
-
-```bash
-Host vm.example.com
-    ProxyCommand bash -c '/usr/local/bin/cloudflared access ssh-gen --hostname %h; ssh -tt %r@cfpipe-vm.example.com >&2 <&1'
-```
+If you prefer to configure manually, this is an example of the generated SSH config:
 
 ```bash
-Host cfpipe-vm.example.com
+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
@@ -82,4 +84,6 @@ Host cfpipe-vm.example.com
 
 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](/cloudflare-one/applications/non-http/#rendering-in-the-browser).
 
+---
+
 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](/cloudflare-one/policies/filtering/network-policies/ssh-logging).