Skip to content
Snippets Groups Projects
Commit ae38deca authored by Zoey Mertes's avatar Zoey Mertes
Browse files

[Access] Add more documentation around SSH usernames and short lived certs in _ssh-usernames.md

parent 289defc3
No related tags found
No related merge requests found
......@@ -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>
\ No newline at end of file
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment