Configure Teleport to Create Host Users

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

This saves you from having to manually create users for each member of an organization and provides more fine-grained control of permissions on a given host. Host users created by Teleport are transient and will be deleted at the end of an SSH session.

Prerequisites

• A running Teleport cluster version 15.4.22 or above. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

• The tctl admin tool and tsh client tool.

  On Teleport Enterprise, you must use the Enterprise version of tctl, which you can download from your Teleport account workspace. Otherwise, visit Installation for instructions on downloading tctl and tsh for Teleport Community Edition.

• A running Linux server registered with Teleport. See the Server Access Getting Started Guide for how to add a server to your Teleport cluster. We recommend enrolling a server that runs in a demo environment for the purpose of this guide until you are familiar with the instructions.
• 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 check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands using your current credentials. tctl is supported on macOS and Linux machines. For example:

  tsh login --proxy=teleport.example.com --user=email@example.com
  tctl status
  Cluster  teleport.example.com
  Version  15.4.22
  CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

  If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.

Step 1/3. Configure RBAC

In this section, you will configure a Teleport role that enables host user creation.

When a Teleport user accesses an SSH Service instance, Teleport checks each of the user's roles that match the instance. If at least one role matches the instance but does not set create_host_user_mode, automatic user creation will be disabled. Roles that do not match the server will not be checked.

To enable host user creation, you will:

• Label your server so you can match it with a Teleport role that enables host user creation.
• Create a role that enables host user creation for servers with the label you added.
• For the purpose of this guide, create a Teleport user with only the role you created.

Label your server

1. Access the server you enrolled with Teleport before beginning this guide and open the Teleport configuration file, which is /etc/teleport.yaml by default.

2. Make the following change to the configuration file:

     labels:
   +   app: "nginx"
   

3. Restart Teleport on the server.

Define a Teleport role

The following role specification allows users to log in as nginxrestarter on any matching server. Add this content to a file called auto-users.yaml:

kind: role
version: v5
metadata:
  name: auto-users
spec:
  options:
    # Allow automatic creation of users.
    create_host_user_mode: keep
  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:
      "app": "nginx"

The create_host_user_mode field enables host user creation when the value is keep. When a user with the auto-users role logs in to a server that matches the app:nginx label, the Teleport SSH Service creates a host user, adds it to the groups listed in host_groups, and gives it the sudoer permissions specified in the host_sudoers field. In this case, the new user receives permission to restart the Nginx service as root.

kind: role
version: v5
metadata:
  name: auto-users
spec:
  options:
    create_host_user_mode: keep
  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:
      "app": "nginx"

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

Create the role:

tctl create -f auto-users.yaml
role 'auto-users' has been created

Create a Teleport user

1. Run the following command to create a Teleport user with the auto-users role:

   tctl users add demo-user --roles=auto-users --logins=nginxrestarter

2. Follow the instructions in your terminal to visit the Teleport Web UI and create the user.

Step 2/3. [Optional] Configure the UID and GID for the created users

If the user has the host_user_uid and host_user_gid traits specified, when the host user is being created the UID and GID will be set to those values.

These values can either be set manually when creating or updating the user through tctl, or it can be set via SSO attributes of the same name.

If a group with the specified GID does not already exist, a group will be created with the same login name as the user being created.

kind: user
metadata:
  name: demo-user
spec:
  ...
  traits:
    logins:
    - nginxrestarter
    host_user_gid:
    # gid and uid values must be quoted.
    - "1234"
    host_user_uid:
    - "5678"

Step 3/3 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
tsh ssh nginxrestarter@develnode
grep "nginxrestarter" /etc/passwd
nginxrestarter:x:1001:1003::/home/nginxrestarter:/bin/bash
grep "other" /etc/group
other:x:1002:nginxrestarter
exit
tsh ssh admin@develnode # checking the user was deleted after logout
grep "nginxrestarter" /etc/passwd
echo $?
1

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

The Teleport SSH Service executes useradd to create new users on the host, and returns an error if it cannot find the useradd binary. The useradd command adds the user to the groups specified in the Teleport user's roles, and Teleport separately creates a new home directory with the name of the new host user.

The SSH Service executes useradd --no-create-home --home-dir <home> <username> --groups <groups> --uid <uid> --gid <gid> when adding a user, with all other options using system defaults. For example, it associates the user with the default login shell for the host, which you can specify by setting the SHELL field in /etc/default/useradd. See the useradd manual for your system for a full description of the default behavior.

The Teleport SSH Service also creates a file 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. When the SSH session ends, the user and their home directory will be kept on the machine. It is possible to remove the user by setting create_host_user_mode to insecure-drop in the role definition. However, the potential for a user id to be reused on the system opens up a number of potential security risks, so we recommend using keep mode unless you have a specific need and understand the potential impacts.

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

Migrating unmanaged users

Host users created with create_host_user_mode: keep prior to v14.3.24, v15.4.16, and v16.1.8 will not be managed by later versions of Teleport. In order to migrate these users automatically on their next session, you can add teleport-keep to your role's host_groups. Host users can also be migrated manually by adding them to the teleport-keep group directly on the hosts you wish to migrate.

Next steps

• Configure automatic user provisioning for database access.
• Configure automatic user provisioning with [Terraform](../../../reference/terraform-provider/#specoptions Note when using the terraform provider that some values may be different than described in this guide.