Configure Teleport to Create Host Users

Report an IssueView as Markdown

Is this page helpful?

How can we improve this page?

Teleport's SSH Service can automatically create local Unix users on a server, and can grant those users temporary sudo permissions. These are two distinct capabilities:

• Host user creation creates a local Unix user when a Teleport user opens an SSH session (or, for static host users, independently of any session), based on the user's Teleport roles.
• Host sudoers writes a temporary entry to /etc/sudoers.d granting the login user specific sudo permissions.

Host user creation saves you from manually managing a Unix account for each member of your organization and gives you fine-grained, per-host control of permissions. As a security best practice, Teleport provisions these users and keeps them on the host for auditability, though they can be configured to be deleted at the end of an SSH session if required by your environment.

How it works

These two capabilities are configured on the same Teleport roles and are often used together, but they operate independently.

Host user creation behavior: When a user logs into a Teleport Node, the SSH service checks if the user's roles permit automatic user creation. If permitted, it executes useradd to provision the user and assign them to the specified groups.

Host sudoers behavior: If the user's roles include host_sudoers entries, Teleport writes a temporary sudoers file to /etc/sudoers.d for the user you log in as, lasting the duration of the session. This is independent of host user creation. The login user may be one Teleport creates for this session, a host user Teleport created earlier (in keep mode or as a static host user), or a user that already existed on the host outside of Teleport. When host user creation does apply, Teleport writes the sudoers file after creating the user.

In this guide, you will:

• Choose between enabling automatic host user creation, which takes place during an SSH session, and static host user creation, which takes place independently of an SSH session.
• Configure Teleport roles to enable your chosen host user creation mode.
• For automatic host user creation, configure your target server to support the created host users.
• For static host user creation, apply a dynamic Teleport resource that configures the created host user.
• Test host user creation on a Teleport-protected server.

Prerequisites

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

• The tctl and tsh clients.

  Installing tctl and tsh clients

  1. Determine the version of your Teleport cluster. The tctl and tsh clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at /v1/webapi/find and use a JSON query tool to obtain your cluster version. Replace teleport.example.com:443 with the web address of your Teleport Proxy Service:

     Mac/Linux

     TELEPORT_DOMAIN=teleport.example.com:443
     TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"

     Windows - Powershell

     $TELEPORT_DOMAIN = "teleport.example.com:443"
     $TELEPORT_VERSION = (Invoke-RestMethod -Uri "https://${TELEPORT_DOMAIN}/v1/webapi/find").server_version

  2. Follow the instructions for your platform to install tctl and tsh clients:

     Mac

     Download the signed macOS .pkg installer for Teleport, which includes the tctl and tsh clients:

     curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg

     In Finder double-click the pkg file to begin installation.

     danger

     Using Homebrew to install Teleport is not supported. The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security.

     Windows - Powershell

     curl.exe -O https://cdn.teleport.dev/teleport-v$TELEPORT_VERSION-windows-amd64-bin.zip
     Unzip the archive and move the `tctl` and `tsh` clients to your %PATH%
     NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP.
     Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\<username>) instead.

     Linux

     All of the Teleport binaries in Linux installations include the tctl and tsh clients. For more options (including RPM/DEB packages and downloads for i386/ARM/ARM64) see our installation page.

     curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     cd teleport
     sudo ./install
     Teleport binaries have been copied to /usr/local/bin

• A running Linux server registered with Teleport. See the 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 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. For example, run the following command, assigning teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and [email protected] to your Teleport username:

  tsh login --proxy=teleport.example.com --user=[email protected]
  tctl status
  Cluster  teleport.example.com
  Version  19.0.0-dev
  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.

Automatic host users

In this section, you will configure Teleport to create local users when a Teleport user starts an SSH session.

Step 1/4. Configure RBAC

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.

To enable host user creation, you will first label your server, and then map a Teleport role to it.

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

Below are examples of how to configure roles for host user creation, host sudoers, and a combined approach.

Example A: Configuring Host User Creation (Only)

The following role enables user creation without granting any sudo privileges. The create_host_user_mode field enables host user creation when the value is keep.

kind: role
version: v8
metadata:
  name: auto-users-basic
spec:
  options:
    create_host_user_mode: keep
    create_host_user_default_shell: /bin/bash
  allow:
    logins: [ "developer" ]
    host_groups: [ubuntu, other]
    node_labels:
      "app": "nginx"

Example B: Configuring Host Sudoers (Only)

If you already have host user creation enabled on another role, you can isolate host_sudoers permissions into a secondary role.

kind: role
version: v8
metadata:
  name: auto-users-sudo
spec:
  allow:
    logins: [ "developer" ]
    host_sudoers: [
       "ALL = (root) NOPASSWD: /usr/bin/systemctl restart nginx.service"
    ]
    node_labels:
      "app": "nginx"

Example C: Combined Example

The following role specification combines both features. Add this content to a file called auto-users.yaml. It allows users to log in as nginxrestarter on any matching server, creates the user, and grants them sudo permission to restart Nginx.

kind: role
version: v8
metadata:
  name: auto-users
spec:
  options:
    create_host_user_mode: keep
    create_host_user_default_shell: /bin/bash
  allow:
    logins: [ "nginxrestarter" ]
    host_groups: [ubuntu, nginx, other]
    host_sudoers: [
       "ALL = (root) NOPASSWD: /usr/bin/systemctl restart nginx.service"
    ]
    node_labels:
      "app": "nginx"

Customizing host user creation

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.

When multiple roles contain host_sudoers entries, the sudoers file will have the entries written to it ordered by role name.

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: v8
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"

If a server must never allow the automatic creation of Unix users you can set disable_create_host_user to true in the Node's configuration:

# 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

In low-security environments, you can set create_host_user_mode to insecure-drop, which deletes users once the session ends. However, in this mode it is possible for a created user to get the same UID as a previously deleted user, which would give the new user access to all of the old user's files if they are not deleted. Use keep mode unless you strictly require users to be automatically removed.

Create the combined role:

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

tip

You can also create and edit roles using the Web UI. Go to Access -> Roles and click Create New Role or pick an existing role to edit.

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/4. [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"

warning

If multiple entries are specified in the host_user_uid or host_user_gid only the first entry will be used.

For Teleport users that don't have a host_user_uid trait, starting from Teleport 17.3, it's possible to configure the cluster to assign the same UID for any given username for automatically created host users across all Teleport SSH instances.

Edit your cluster authentication preference using the following command:

tctl edit cluster_auth_preference

In your editor, ensure that your cluster_auth_preference includes a stable_unix_user_config field similar to the following:

kind: cluster_auth_preference
version: v2
metadata:
  name: cluster-auth-preference
spec:
  # ...
  stable_unix_user_config:
    enabled: true
    first_uid: 90000
    last_uid: 95000

The range of UIDs between first_uid and last_uid (inclusive) will be used by Teleport to assign UIDs for new users, and you should make sure it's not a range of UIDs already in use by other services or workloads across your fleet of servers. While UID allocations in Linux can vary, we recommend sticking to one of the available ranges listed in the systemd documentation for "Users, Groups, UIDs and GIDs on systemd Systems".

Once enabled, all Teleport SSH instances (of version 17.3 and newer) will use the UID provided by the control plane when automatically creating a new host user, if no other UID is specified by the user trait.

note

Teleport will only use the UID defined by the control plane if the create_host_user_mode is keep (and not insecure-drop), and only for automatically created host users that were created after the feature was enabled. The UID will not be applied to users that already exist, and it will not take effect for static host users.

You can inspect the list of assigned UIDs with the following command:

tctl stable-unix-users ls

Step 3/4. Configure sudoers on your Linux servers

Teleport host user creation leverages the sudoers.d directory for new users. For CentOS builds, ensure that the following line is present in your sudoers file. Ignore for any other Linux distros:

#includedir /etc/sudoers.d

In the sudoers file, the # symbol is typically used to indicate comments. However, in this context, #includedir is a directive and not a comment.

For Debian-based systems, you might encounter @includedir /etc/sudoers.d, which serves a similar purpose. Ensure that the correct directive is used based on your operating system.

Step 4/4 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

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.

Static host users

In this section, you will configure Teleport to create local users independently of an SSH session. Static host users require Teleport version >=16.3.0 on auth servers, SSH services, and tctl.

Step 1/3. Configure RBAC

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: v8
metadata:
  name: auto-users
spec:
  allow:
    logins: ["nginxrestarter"]
    node_labels:
      "app": "nginx"

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. Create the static host user

Add this content to a file called nginxrestarter.yaml:

kind: static_host_user
metadata:
  name: nginxrestarter
spec:
  matchers:
    # Use either node_labels or node_labels_expression to select which servers
    # to create the host user on. Only one is required.
    - node_labels:
      - name: app
        values: ["nginx"]
      # node_labels_expression: 'labels["app"] == "nginx"'
      
      # List of host groups the created user will be added to. Any that don't already exist are created.
      groups: [ubuntu, nginx, other]
      
      # List of entries to include in a temporary sudoers file created in /etc/sudoers.d
      sudoers: [
        "ALL = (root) NOPASSWD: /usr/bin/systemctl restart nginx.service"
      ]
      # UID of the host user. Optional.
      # uid: 1234
      # GID of the host user. Optional.
      # gid: 1234
      # Default shell for the created user. Optional.
      # default_shell: /bin/bash
      # Whether or not static host user provisioning should automatically take ownership of existing users
      # created outside of Teleport. Optional.
      # take_ownership_if_user_exists: true

The name of the static host user resource must match the login of the user to be created. A server will only provision the user if a single defined matcher is satisfied. If there are multiple matches for a single static host user resource, or if the user already exists and take_ownership_if_user_exists is not set to true, then the server will refuse to provision the user.

Create the static host user:

tctl create -f nginxrestarter.yaml
static_host_user 'nginxrestarter' has been created

note

Deleting the static host user resource does not remove the host user from any servers it has been applied to.

Step 3/3. Test

Connect to the remote Node via tsh to verify that the host user was created:

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

Under the hood

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 are kept on the machine by default. To have Teleport remove them instead as part of session-end cleanup, set create_host_user_mode to insecure-drop in the role definition. Note that insecure-drop only removes users that Teleport created; if the user already existed on the host, Teleport leaves the account and its home directory in place.

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

keep mode users from previous versions of Teleport

Automatic 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.

Static host users

By default, static host user provisioning will not take ownership of any existing users created outside of Teleport. In order to configure Teleport to automatically take ownership of any unmanaged users that collide with a static host user, the take_ownership_if_user_exists flag can be set to true on the static host user resource. This will bring the existing user under Teleport's management and override the groups assigned to that user. Similar to migrating teleport-keep users, it is possible to migrate users manually by adding them to the teleport-static group directly on the hosts.

Next steps

• Configure automatic user provisioning for database access.
• Configure automatic user provisioning for desktop access.
• Configure automatic user provisioning with Terraform. Note when using the terraform provider that some values may be different than described in this guide.