
Teleport
Configure Teleport to Create Host Users
- Version 15.x
- Version 14.x
- Version 13.x
- Version 12.x
- Older Versions
- Available for:
- OpenSource
- Team
- Cloud
- Enterprise
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. For details on how to set this up, see the Getting Started guide.
-
The
tctl
admin tool andtsh
client tool version >= 14.0.1.See Installation for details.
-
A Teleport Team account. If you don't have an account, sign up to begin your free trial.
-
The Enterprise
tctl
admin tool andtsh
client tool, version >= 13.3.9.You can download these tools from the Cloud Downloads page.
-
A running Teleport Enterprise cluster. For details on how to set this up, see the Enterprise Getting Started guide.
-
The Enterprise
tctl
admin tool andtsh
client tool version >= 14.0.1.You can download these tools by visiting your Teleport account workspace.
Please use the latest version of Teleport Enterprise documentation.
To check version information, run the tctl version
and tsh version
commands.
For example:
tctl versionTeleport Enterprise v13.3.9 git:api/14.0.0-gd1e081e go1.21
tsh versionTeleport v13.3.9 go1.21
Proxy version: 13.3.9Proxy: teleport.example.com
- 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 check that you can connect to your Teleport cluster, sign in with
tsh login
, then verify that you can runtctl
commands on your administrative workstation 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 14.0.1
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.
Step 1/3. Configure a role
First, create a role with create_host_user_mode
set to drop
or keep
.
Setting the option to drop
will create transient users that are deleted once the
session ends. Setting it to keep
will create permanent users on the host 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_mode: drop
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.yamlrole '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 specify create_host_user_mode
to be either keep
or drop
,
automatic user creation will be disabled. Roles that do not match the server will
not be checked.
If multiple roles match where one might specify keep
and another drop
,
Teleport will default to keep
, retaining the user on the server after the session
ends.
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: drop
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_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
Assign the auto-users
role to your Teleport user by running the appropriate
commands for your authentication provider:
-
Retrieve your local user's configuration resource:
tctl get users/$(tsh status -f json | jq -r '.active.username') > out.yaml -
Edit
out.yaml
, addingauto-users
to the list of existing roles:roles: - access - auditor - editor + - auto-users
-
Apply your changes:
tctl create -f out.yaml -
Sign out of the Teleport cluster and sign in again to assume the new role.
-
Retrieve your
github
authentication connector:tctl get github/github --with-secrets > github.yamlNote that the
--with-secrets
flag adds the value ofspec.signing_key_pair.private_key
to thegithub.yaml
file. Because this key contains a sensitive value, you should remove the github.yaml file immediately after updating the resource. -
Edit
github.yaml
, addingauto-users
to theteams_to_roles
section.The team you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the team must include your user account and should be the smallest team possible within your organization.
Here is an example:
teams_to_roles: - organization: octocats team: admins roles: - access + - auto-users
-
Apply your changes:
tctl create -f github.yaml -
Sign out of the Teleport cluster and sign in again to assume the new role.
-
Retrieve your
saml
configuration resource:tctl get --with-secrets saml/mysaml > saml.yamlNote that the
--with-secrets
flag adds the value ofspec.signing_key_pair.private_key
to thesaml.yaml
file. Because this key contains a sensitive value, you should remove the saml.yaml file immediately after updating the resource. -
Edit
saml.yaml
, addingauto-users
to theattributes_to_roles
section.The attribute you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the group must include your user account and should be the smallest group possible within your organization.
Here is an example:
attributes_to_roles: - name: "groups" value: "my-group" roles: - access + - auto-users
-
Apply your changes:
tctl create -f saml.yaml -
Sign out of the Teleport cluster and sign in again to assume the new role.
-
Retrieve your
oidc
configuration resource:tctl get oidc/myoidc --with-secrets > oidc.yamlNote that the
--with-secrets
flag adds the value ofspec.signing_key_pair.private_key
to theoidc.yaml
file. Because this key contains a sensitive value, you should remove the oidc.yaml file immediately after updating the resource. -
Edit
oidc.yaml
, addingauto-users
to theclaims_to_roles
section.The claim you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the group must include your user account and should be the smallest group possible within your organization.
Here is an example:
claims_to_roles: - name: "groups" value: "my-group" roles: - access + - auto-users
-
Apply your changes:
tctl create -f oidc.yaml -
Sign out of the Teleport cluster and sign in again to assume the new role.
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: some_teleport_user
spec:
...
traits:
logins:
- root
- alex
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.
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
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.
Aside from specifying a home directory and groups, the SSH Service executes
useradd
with the 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, however once the SSH session ends, the user will be automatically removed and their home directory will be deleted, 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.
Next steps
- Configure automatic user provisioning for Database Access.
- Configure automatic user provisioning for Desktop Access.