Local Users

In Teleport, local users are users managed directly via Teleport, rather than a third-party identity provider. All local users are stored in Teleport's cluster state backend, which contains the user's name, their roles and traits, and a bcrypt password hash.

This guide shows you how to:

• Add local users
• Edit existing users
• Delete users

Prerequisites

• A running Teleport cluster version 15.4.22 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 and tsh client tool.

  On Teleport Enterprise, you must use the Enterprise version of tctl, which you can download from your Teleport account workspace. Otherwise, visit Installation for instructions on downloading tctl and tsh for Teleport Community Edition.

• 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. tctl is supported on macOS and Linux machines. For example:

  tsh login --proxy=teleport.example.com --user=email@example.com
  tctl status
  Cluster  teleport.example.com
  Version  15.4.22
  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.

Adding local users

A user identity in Teleport exists in the scope of a cluster. A Teleport administrator creates Teleport user accounts and maps them to the roles they can use.

Let's look at this table:

Let's add a new user to Teleport using the tctl tool:

tctl users add joe --logins=joe,root --roles=access,editor

tctl users add joe --logins=joe,root --roles=access,editor,reviewer

Teleport generates an auto-expiring token (with a TTL of one hour) and prints the token URL, which must be used before the TTL expires.

User "joe" has been created but requires a password. Share this URL with the user to complete user setup, link is valid for 1h:https://<proxy_host>:443/web/invite/<token>
NOTE: Make sure <proxy_host>:443 points at a Teleport proxy which users can access.

The user completes registration by visiting this URL in their web browser, picking a password, and configuring multi-factor authentication. If the credentials are correct, the Teleport Auth Server generates and signs a new certificate, and the client stores this key and will use it for subsequent logins.

The key will automatically expire after 12 hours by default, after which the user will need to log back in with their credentials. This TTL can be configured to a different value.

Once authenticated, the account will become visible via tctl:

tctl users ls

User           Allowed Logins
----           --------------
admin          admin,root
kim            kim
joe            joe,root

Editing users

Admins can edit user entries via tctl.

For example, to see the full list of user records, an administrator can execute:

tctl get users

To edit the user joe:

Dump the user definition into a file:
tctl get user/joe > joe.yaml
... edit the contents of joe.yaml

Update the user record:
tctl create -f joe.yaml

Deleting users

Admins can delete a local user via tctl:

tctl users rm joe

Next steps