Fork me on GitHub

Teleport

Configure Teleport to Create Host Users

Improve

Teleport's SSH Service can be configured to automatically create local Unix users upon login.

Host users created by Teleport are transient and will be deleted at the end of an SSH session. This feature has overlap with the PAM integration, however it provides some additional convenience of not having to manually configure a PAM script to create and delete users.

It also has benefits over manually creating users as it allows for separate host users for each member of an organization. This provides more fine-grained control of permissions on a given host.

Prerequisites

  • A running Teleport cluster. For details on how to set this up, see one of our Getting Started guides.

  • The tctl admin tool and tsh client tool version >= 10.1.2.

    tctl version

    Teleport v10.1.2 go1.18

    tsh version

    Teleport v10.1.2 go1.18

    See Installation for details.

  • A running Teleport cluster. For details on how to set this up, see our Enterprise Getting Started guide.

  • The tctl admin tool and tsh client tool version >= 10.1.2, which you can download by visiting the customer portal.

    tctl version

    Teleport v10.1.2 go1.18

    tsh version

    Teleport v10.1.2 go1.18

  • A Teleport Cloud account. If you do not have one, visit the sign up page to begin your free trial.

  • The tctl admin tool and tsh client tool version >= 9.3.10. To download these tools, visit the Downloads page.

    tctl version

    Teleport v9.3.10 go1.18

    tsh version

    Teleport v9.3.10 go1.18

  • A running Teleport Node. See the Server Access Getting Started Guide for how to add a Node to your Teleport cluster.
  • The following utilities should be available in the PATH for the Teleport SSH Service, since it must execute these commands in order to create transient users:
    • useradd
    • userdel
    • usermod
    • groupadd
    • getent
    • visudo

To connect to Teleport, log in to your cluster using tsh, then use tctl remotely:

tsh login --proxy=teleport.example.com [email protected]
tctl status

Cluster teleport.example.com

Version 10.1.2

CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

You can run subsequent tctl commands in this guide on your local machine.

For full privileges, you can also run tctl commands on your Auth Service host.

To connect to Teleport, log in to your cluster using tsh, then use tctl remotely:

tsh login --proxy=myinstance.teleport.sh [email protected]
tctl status

Cluster myinstance.teleport.sh

Version 9.3.10

CA pin sha256:sha-hash-here

You must run subsequent tctl commands in this guide on your local machine.

Step 1/2. Configure a role

First, create a role with create_host_user set to true. This will allow users with this role to have transient host users created at login time.

The following role specification will allow users to log in as nginxrestarter on any matching Node. The host user will be created and added to the groups listed in host_groups. They will also be given permission to restart the Nginx service as root.

Save the file below as auto-users.yaml

kind: role
version: v5
metadata:
  name: auto-users
spec:
  options:
    # Allow automatic creation of users.
    create_host_user: true
  allow:
    logins: [ "nginxrestarter" ]
    # List of host groups the created user will be added to. Any that don't already exist are created.
    host_groups: [ubuntu, nginx, other]
    # List of entries to include in a temporary sudoers file created in /etc/sudoers.d
    host_sudoers: [
       # This line will allow the `nginxrestarter` user to run
       # `systemctl restart nginx.service` as
       # root without requiring a password.
       # The sudoers entries will be prefixed with `nginxrestarter` in this case.
       # sudoers file reference documentation: https://www.sudo.ws/docs/man/1.8.17/sudoers.man/
       "ALL = (root) NOPASSWD: /usr/bin/systemctl restart nginx.service"
    ]
    node_labels:
      'env': 'devel'

Create the role:

tctl create -f auto-users.yaml

role 'auto-users' has been created

Each value of the logins field must conform to the username requirements of the Linux distribution being used. See User/Group Name Syntax for requirements in common distributions.

Warning

When a Teleport user accesses a Node, Teleport Server Access checks each of the user's roles that match the Node. If at least one role matches the Node but does not include create_host_user: true, automatic user creation will be disabled. Roles that do not match the Node will not be checked.

If a role includes a deny rule that sets host_sudoers to '*', the user will have all sudoers entries removed when accessing matching Nodes, otherwise deny rules are matched literally when filtering:

kind: role
version: v5
metadata:
  name: auto-users
spec:
  options:
    create_host_user: true
  deny:
    host_sudoers: [
       "*" # ensure that users in this role never have sudoers files created on matching Nodes
       "ALL=(ALL) NOPASSWD: ALL" # host_sudoers entries matching this are filtered out
    ]
    node_labels:
      'env': 'devel'

If an SSH Node must never allow the automatic creation of transient Unix users you can set disable_create_host_users to true in the Node's configuration:

# teleport.yml
teleport:
  nodename: node
ssh_service:
  enabled: true
  # Disable automatic host user creation on this Node, regardless of role permissions.
  disable_create_host_users: true

Step 2/2 Test host user creation

When you connect to a remote Node via tsh, and host user creation is enabled, the Teleport SSH Service will automatically create a user on the host:

tsh login
grep "nginxrestarter" /etc/passwd

nginxrestarter:x:1001:1003::/home/nginxrestarter:/bin/bash

grep "other" /etc/group

other:x:1002:nginxrestarter

exit
tsh ssh [email protected] # checking the user was deleted after logout
grep "teleportuser" /etc/passwd
echo $?

1

When logging in, the nginxrestarter user and any groups that do not already exist will be created on the host. The nginxrestarter user will be added to the ubuntu, nginx and other groups as specified in the host_groups field.

A file will also be created in /etc/sudoers.d with the contents of the host_sudoers file written with one entry per line, each prefixed with the username of the user that has logged in.

The session can then proceed as usual, however once the SSH session ends, the user will be automatically removed and their home directory will be deleted. Files owned by the deleted user, created outside the home directory, will remain in place. Groups that were created will remain on the system after the session ends.

Should a Teleport SSH instance be restarted while a session is in progress, the user will be cleaned up at the next Teleport restart.