Configure Teleport to Create Host Users
- Available for:
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.
- 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:
- To check that you can connect to your Teleport cluster, sign in with
tsh login, then verify that you can run
tctlcommands using your current credentials.
tctlis supported on macOS and Linux machines. For example:If you can connect to the cluster and run thetsh login --proxy=teleport.example.com --user=[email protected]tctl status
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
tctl statuscommand, you can use your current credentials to run subsequent
tctlcommands from your workstation. If you host your own Teleport cluster, you can also run
tctlcommands on the computer that hosts the Teleport Auth Service for full permissions.
First, create a role with
create_host_user_mode set to
The following role specification will allow users to log in as
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
create_host_user_mode can also be set 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
unless you really need users to be removed.
Save the file below as
# Allow automatic creation of users.
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
# 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"
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.
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.
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
'*', the user will
have all sudoers entries removed when accessing matching Nodes, otherwise
rules are matched literally when filtering:
"*" # 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
If an SSH Node must never allow the automatic creation of transient Unix users
you can set
true in the Node's configuration:
# Disable automatic host user creation on this Node, regardless of role permissions.
auto-users role to your Teleport user by running the appropriate
commands for your authentication provider:
If the user has the
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
tctl, or it can be set via SSO attributes of the same
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.
# gid and uid values must be quoted.
If multiple entries are specified in the
host_user_gid only the first entry will be used.
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 logintsh ssh nginxrestarter@develnodegrep "nginxrestarter" /etc/passwd
nginxrestarter:x:1001:1003::/home/nginxrestarter:/bin/bashgrep "other" /etc/group
other:x:1002:nginxrestarterexittsh ssh admin@develnode # checking the user was deleted after logoutgrep "nginxrestarter" /etc/passwdecho $?
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
other groups, as specified in the
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
creates a new home directory with the name of the new host user and adds the
user to the groups specified in the Teleport user's roles.
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
/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, however once the SSH session ends, the user
will be automatically removed and their home directory will be deleted with
userdel --remove <username>, as the
matching role specified they should be dropped. 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.