
Teleport's SSH Service can be configured to automatically create local Unix users upon login.
Host users created by Teleport are transient and will be deleted at the end of an SSH session. This feature has overlap with the PAM integration, however it provides some additional convenience of not having to manually configure a PAM script to create and delete users.
It also has benefits over manually creating users as it allows for separate host users for each member of an organization. This provides more fine-grained control of permissions on a given host.
Prerequisites
-
A running Teleport cluster. For details on how to set this up, see one of our Getting Started guides.
-
The
tctl
admin tool andtsh
client tool version >= 12.1.1.tctl versionTeleport v12.1.1 go1.19
tsh versionTeleport v12.1.1 go1.19
See Installation for details.
-
A running Teleport cluster. For details on how to set this up, see our Enterprise Getting Started guide.
-
The Enterprise
tctl
admin tool andtsh
client tool version >= 12.1.1, which you can download by visiting the customer portal.tctl versionTeleport Enterprise v12.1.1 go1.19
tsh versionTeleport v12.1.1 go1.19
Please use the latest version of Teleport Enterprise documentation.
- 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 connect to Teleport, log in to your cluster using tsh
, then use tctl
remotely:
tsh login --proxy=teleport.example.com [email protected]tctl statusCluster teleport.example.com
Version 12.1.1
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
You can run subsequent tctl
commands in this guide on your local machine.
For full privileges, you can also run tctl
commands on your Auth Service host.
To connect to Teleport, log in to your cluster using tsh
, then use tctl
remotely:
tsh login --proxy=myinstance.teleport.sh [email protected]tctl statusCluster myinstance.teleport.sh
Version 12.1.1
CA pin sha256:sha-hash-here
You must run subsequent tctl
commands in this guide on your local machine.
Step 1/2. Configure a role
First, create a role with create_host_user
set to true
. This will allow users
with this role to have transient host users created 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: true
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 a Node, Teleport Server Access checks each of the
user's roles that match the Node. If at least one role matches the Node but does not
include create_host_user: true
, automatic user creation will be disabled. Roles that
do not match the Node will not be checked.
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: true
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 following
commands, depending on whether you authenticate as a local Teleport user or via
the github
, saml
, or oidc
authentication connectors:
Retrieve your local user's configuration resource:
tctl get users/$(tsh status -f json | jq -r '.active.username') > out.yaml
Edit out.yaml
, adding auto-users
to the list of existing roles:
roles:
- access
- auditor
- editor
+ - auto-users
Apply your changes:
tctl create -f out.yaml
Retrieve your github
configuration resource:
tctl get github/github --with-secrets > github.yaml
Edit github.yaml
, adding auto-users
to the
teams_to_roles
section. The team you will map to this role will depend on how
you have designed your organization's RBAC, but it should be the smallest team
possible within your organization. This team must also include your user.
Here is an example:
teams_to_roles:
- organization: octocats
team: admins
roles:
- access
+ - auto-users
Apply your changes:
tctl create -f github.yaml
Retrieve your saml
configuration resource:
tctl get saml/mysaml --with-secrets > saml.yaml
Edit saml.yaml
, adding auto-users
to the
attributes_to_roles
section. The attribute you will map to this role will
depend on how you have designed your organization's RBAC, but it should be the
smallest group possible within your organization. This group must also include
your user.
Here is an example:
attributes_to_roles:
- name: "groups"
value: "my-group"
roles:
- access
+ - auto-users
Apply your changes:
tctl create -f saml.yaml
Retrieve your oidc
configuration resource:
tctl get oidc/myoidc --with-secrets > oidc.yaml
Edit oidc.yaml
, adding auto-users
to the
claims_to_roles
section. The claim you will map to this role will depend on
how you have designed your organization's RBAC, but it should be the smallest
group possible within your organization. This group must also include your
user.
Here is an example:
claims_to_roles:
- name: "groups"
value: "my-group"
roles:
- access
+ - auto-users
Apply your changes:
tctl create -f saml.yaml
Log out of your Teleport cluster and log in again to assume the new role.
Step 2/2 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 [email protected]grep "nginxrestarter" /etc/passwdnginxrestarter:x:1001:1003::/home/nginxrestarter:/bin/bash
grep "other" /etc/groupother:x:1002:nginxrestarter
exittsh ssh [email protected] # checking the user was deleted after logoutgrep "nginxrestarter" /etc/passwdecho $?1
When logging in, the nginxrestarter
user and any groups that do not already exist
will be created on the host. The nginxrestarter
user will be added to the ubuntu
,
nginx
and other
groups as specified in the host_groups
field.
A file will also be created 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. 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.