Teleport
Configure Teleport to Create Host Users
- Version 17.x
- Version 16.x
- Version 15.x
- Version 14.x
- Older Versions
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 16.4.2 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 andtsh
client tool.Visit Installation for instructions on downloading
tctl
andtsh
.
- 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 runtctl
commands using your current credentials. For example:If you can connect to the cluster and run thetsh login --proxy=teleport.example.com --user=[email protected]tctl statusCluster teleport.example.com
Version 16.4.2
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
tctl status
command, you can use your current credentials to run subsequenttctl
commands from your workstation. If you host your own Teleport cluster, you can also runtctl
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/3. 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. 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
-
Access the server you enrolled with Teleport before beginning this guide and open the Teleport configuration file, which is
/etc/teleport.yaml
by default. -
Make the following change to the configuration file:
labels: + app: "nginx"
-
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
create_host_user_default_shell: /bin/bash
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. In Teleport 16.4.0 and later,
the default shell for a created user can be configured with create_host_user_default_shell
.
Otherwise the host's default shell will be used.
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: 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"
If a server must never allow the automatic creation of transient 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 also 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 really need users to
be removed.
Create the role:
tctl create -f auto-users.yamlrole 'auto-users' has been created
Create a Teleport user
-
Run the following command to create a Teleport user with the
auto-users
role:tctl users add demo-user --roles=auto-users --logins=nginxrestarter -
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"
If multiple entries are specified in the host_user_uid
or host_user_gid
only the first entry will be used.
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 logintsh ssh nginxrestarter@develnodegrep "nginxrestarter" /etc/passwdnginxrestarter:x:1001:1003::/home/nginxrestarter:/bin/bash
grep "other" /etc/groupother:x:1002:nginxrestarter
exittsh ssh admin@develnode # checking the user was deleted after logoutgrep "nginxrestarter" /etc/passwdecho $?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.
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
-
Access the server you enrolled with Teleport before beginning this guide and open the Teleport configuration file, which is
/etc/teleport.yaml
by default. -
Make the following change to the configuration file:
labels: + app: "nginx"
-
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:
allow:
logins: ["nginxrestarter"]
node_labels:
"app": "nginx"
Create the role:
tctl create -f auto-users.yamlrole 'auto-users' has been created
Create a Teleport user
-
Run the following command to create a Teleport user with the
auto-users
role:tctl users add demo-user --roles=auto-users --logins=nginxrestarter -
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: [
# 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"
]
# 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
# Add additional matchers if needed to configure nginxrestarter differently
# on different servers.
# - node_labels:
# ...
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, then the server will refuse to provision the user.
Create the static host user:
tctl create -f nginxrestarter.yamlstatic_host_user 'nginxrestarter' has been created
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 logintsh ssh nginxrestarter@develnodegrep "nginxrestarter" /etc/passwdnginxrestarter:x:1001:1003::/home/nginxrestarter:/bin/bash
grep "other" /etc/groupother: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 will be kept on the machine. It is possible to remove automatic host users
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
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.
Next steps
- Configure automatic user provisioning for Database Access.
- Configure automatic user provisioning for desktop access.