Skip to main content
Version: 17.x

Local Users

Report an issue with this page

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:

Prerequisites​

  • A running Teleport cluster. If you do not have one, read Getting Started.

  • 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:

      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.

  • 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 protected] to your Teleport username: 
    tsh login --proxy=teleport.example.com --user=[email protected]
    tctl status
    Cluster  teleport.example.com
    Version  17.7.7
    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:

Teleport UserSSH LoginsDescription
joejoe, rootTeleport user joe can log in as user joe or root on SSH servers.
bobbobTeleport user bob can log in as user bob on SSH servers.
kimTeleport user 'kim' has no designated SSH logins.

SSH logins are some of the user traits available in Teleport roles. For all supported traits, see the reference for tctl users add.

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

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

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 Service generates and signs a new user certificate.

The certificate 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           Roles
----           --------------
admin          editor
kim            access
joe            access,editor

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, run the following command:

tctl edit user/joe

Make your changes, then save and close the file in your editor to apply them.

Deleting users​

Admins can delete a local user via tctl:

tctl users rm joe

Next steps​

In addition to users, you can use tctl to manage roles and other dynamic resources. See our Teleport Resources Reference.

For all available tctl commands and flags, see our CLI Reference.

You can also configure Teleport so that users can log in using an SSO provider. For more information, see: