# Configure Teleport to Create Host Users 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. If you want to get started with Teleport, [sign up](https://goteleport.com/signup) for a free trial or [set up a demo environment](https://goteleport.com/docs/get-started/deploy-community.md). - The `tctl` and `tsh` clients. Installing `tctl` and `tsh` clients 1. Determine the version of your Teleport cluster. The `tctl` and `tsh` clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at `/v1/webapi/find` and use a JSON query tool to obtain your cluster version. Replace teleport.example.com:443 with the web address of your Teleport Proxy Service: ``` $ TELEPORT_DOMAIN=teleport.example.com:443 $ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')" ``` 2. Follow the instructions for your platform to install `tctl` and `tsh` clients: **Mac** Download the signed macOS .pkg installer for Teleport, which includes the `tctl` and `tsh` clients: ``` $ curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg ``` In Finder double-click the `pkg` file to begin installation. --- DANGER Using Homebrew to install Teleport is not supported. The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security. --- **Windows - Powershell** ``` $ curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zip Unzip the archive and move the `tctl` and `tsh` clients to your %PATH% NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP. Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\) instead. ``` **Linux** All of the Teleport binaries in Linux installations include the `tctl` and `tsh` clients. For more options (including RPM/DEB packages and downloads for i386/ARM/ARM64) see our [installation page](https://goteleport.com/docs/installation.md). ``` $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz $ cd teleport $ sudo ./install Teleport binaries have been copied to /usr/local/bin ``` * A running Linux server registered with Teleport. See the [getting started guide](https://goteleport.com/docs/enroll-resources/server-access/getting-started.md) 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 run `tctl` commands using your current credentials. For example, run the following command, assigning teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and email\@example.com to your Teleport username: ``` $ tsh login --proxy=teleport.example.com --user=email@example.com $ tctl status Cluster teleport.example.com Version 19.0.0-dev CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678 ``` If you can connect to the cluster and run the `tctl status` command, you can use your current credentials to run subsequent `tctl` commands from your workstation. If you host your own Teleport cluster, you can also run `tctl` 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/4. 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 1. Access the server you enrolled with Teleport before beginning this guide and open the Teleport configuration file, which is `/etc/teleport.yaml` by default. 2. Make the following change to the configuration file: ``` labels: + app: "nginx" ``` 3. 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. Customizing host user creation Each value of the `logins` field must conform to the username requirements of the Linux distribution being used. See [User/Group Name Syntax](https://systemd.io/USER_NAMES/) 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.yaml role 'auto-users' has been created ``` --- TIP You can also create and edit roles using the Web UI. Go to **Access -> Roles** and click **Create New Role** or pick an existing role to edit. --- #### Create a Teleport user 1. Run the following command to create a Teleport user with the `auto-users` role: ``` $ tctl users add demo-user --roles=auto-users --logins=nginxrestarter ``` 2. Follow the instructions in your terminal to visit the Teleport Web UI and create the user. ### Step 2/4. \[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" ``` --- WARNING If multiple entries are specified in the `host_user_uid` or `host_user_gid` only the first entry will be used. --- For Teleport users that don't have a `host_user_uid` trait, starting from Teleport 17.3, it's possible to configure the cluster to assign the same UID for any given username for automatically created host users across all Teleport SSH instances. Edit your cluster authentication preference using the following command: ``` $ tctl edit cluster_auth_preference ``` In your editor, ensure that your `cluster_auth_preference` includes a `stable_unix_user_config` field similar to the following: ``` kind: cluster_auth_preference version: v2 metadata: name: cluster-auth-preference spec: # ... stable_unix_user_config: enabled: true first_uid: 90000 last_uid: 95000 ``` The range of UIDs between `first_uid` and `last_uid` (inclusive) will be used by Teleport to assign UIDs for new users, and you should make sure it's not a range of UIDs already in use by other services or workloads across your fleet of servers. While UID allocations in Linux can vary, we recommend sticking to one of the available ranges listed in the [systemd documentation for "Users, Groups, UIDs and GIDs on systemd Systems"](https://github.com/systemd/systemd/blob/main/docs/UIDS-GIDS.md). Once enabled, all Teleport SSH instances (of version 17.3 and newer) will use the UID provided by the control plane when automatically creating a new host user, if no other UID is specified by the user trait. --- NOTE Teleport will only use the UID defined by the control plane if the `create_host_user_mode` is `keep` (and not `insecure-drop`), and only for automatically created host users that were created after the feature was enabled. The UID will not be applied to users that already exist, and it will not take effect for static host users. --- You can inspect the list of assigned UIDs with the following command: ``` $ tctl stable-unix-users ls ``` ### Step 3/4. Configure sudoers on your Linux servers Teleport host user creation leverages the `sudoers.d` directory for new users. For CentOS builds, ensure that the following line is present in your sudoers file. Ignore for any other Linux distros: ``` #includedir /etc/sudoers.d ``` In the sudoers file, the `#` symbol is typically used to indicate comments. However, in this context, `#includedir` is a directive and not a comment. For Debian-based systems, you might encounter `@includedir /etc/sudoers.d`, which serves a similar purpose. Ensure that the correct directive is used based on your operating system. ### Step 4/4 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 $ tsh ssh nginxrestarter@develnode $ grep "nginxrestarter" /etc/passwd nginxrestarter:x:1001:1003::/home/nginxrestarter:/bin/bash $ grep "other" /etc/group other:x:1002:nginxrestarter $ exit $ tsh ssh admin@develnode # checking the user was deleted after logout $ grep "nginxrestarter" /etc/passwd $ echo $? 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 1. Access the server you enrolled with Teleport before beginning this guide and open the Teleport configuration file, which is `/etc/teleport.yaml` by default. 2. Make the following change to the configuration file: ``` labels: + app: "nginx" ``` 3. 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.yaml role 'auto-users' has been created ``` #### Create a Teleport user 1. Run the following command to create a Teleport user with the `auto-users` role: ``` $ tctl users add demo-user --roles=auto-users --logins=nginxrestarter ``` 2. 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 # Whether or not static host user provisioning should automatically take ownership of existing users # created outside of Teleport. Optional. # take_ownership_if_user_exists: true # 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, or if the user already exists and `take_ownership_if_user_exists` is not set to `true`, then the server will refuse to provision the user. Create the static host user: ``` $ tctl create -f nginxrestarter.yaml static_host_user 'nginxrestarter' has been created ``` --- NOTE 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 login $ tsh ssh nginxrestarter@develnode $ grep "nginxrestarter" /etc/passwd nginxrestarter:x:1001:1003::/home/nginxrestarter:/bin/bash $ grep "other" /etc/group other: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 --groups --uid --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 ### `keep` mode users from previous versions of Teleport 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. ### Static host users By default, static host user provisioning will not take ownership of any existing users created outside of Teleport. In order to configure Teleport to automatically take ownership of any unmanaged users that collide with a static host user, the `take_ownership_if_user_exists` flag can be set to `true` on the static host user resource. This will bring the existing user under Teleport's management and override the groups assigned to that user. Similar to migrating `teleport-keep` users, it is possible to migrate users manually by adding them to the `teleport-static` group directly on the hosts. ## Next steps - Configure automatic user provisioning for [database access](https://goteleport.com/docs/enroll-resources/database-access/auto-user-provisioning.md). - Configure automatic user provisioning for [desktop access](https://goteleport.com/docs/enroll-resources/desktop-access/reference/user-creation.md). - Configure automatic user provisioning with [Terraform](https://goteleport.com/docs/reference/infrastructure-as-code/terraform-provider/resources/role.md). Note when using the terraform provider that some values may be different than described in this guide.