Fork me on GitHub

Teleport

Configure Teleport to Create Host Users

Improve

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 and tsh client tool version >= 12.1.1.

    tctl version

    Teleport v12.1.1 go1.19

    tsh version

    Teleport 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 and tsh client tool version >= 12.1.1, which you can download by visiting the customer portal.

    tctl version

    Teleport Enterprise v12.1.1 go1.19

    tsh version

    Teleport v12.1.1 go1.19

Cloud is not available for Teleport v.
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 status

Cluster 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 status

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

Warning

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 login
grep "nginxrestarter" /etc/passwd

nginxrestarter:x:1001:1003::/home/nginxrestarter:/bin/bash

grep "other" /etc/group

other:x:1002:nginxrestarter

exit
tsh ssh [email protected] # checking the user was deleted after logout
grep "nginxrestarter" /etc/passwd
echo $?

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.