Fork me on GitHub

Teleport

Local Users

  • Available for:
  • OpenSource
  • Team
  • Cloud
  • Enterprise

In Teleport, local users are users managed directly via Teleport, rather than a third-party identity provider.

This guide shows you how to:

Prerequisites

  • A running Teleport cluster. For details on how to set this up, see the Getting Started guide.

  • The tctl admin tool and tsh client tool version >= 14.0.0.

    See Installation for details.

  • A Teleport Team account. If you don't have an account, sign up to begin your free trial.

  • The Enterprise tctl admin tool and tsh client tool, version >= 13.3.9.

    You can download these tools from the Cloud Downloads page.

  • A running Teleport Enterprise cluster. For details on how to set this up, see the Enterprise Getting Started guide.

  • The Enterprise tctl admin tool and tsh client tool version >= 14.0.0.

    You can download these tools by visiting your Teleport account workspace.

Cloud is not available for Teleport v.
Please use the latest version of Teleport Enterprise documentation.

To check version information, run the tctl version and tsh version commands. For example:

tctl version

Teleport Enterprise v13.3.9 git:api/14.0.0-gd1e081e go1.21


tsh version

Teleport v13.3.9 go1.21

Proxy version: 13.3.9Proxy: teleport.example.com
  • To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands on your administrative workstation using your current credentials. For example:
    tsh login --proxy=teleport.example.com --user=[email protected]
    tctl status

    Cluster teleport.example.com

    Version 14.0.0

    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 UserAllowed OS LoginsDescription
joejoe, rootTeleport user joe can log in to member Nodes as user joe or root on the OS.
bobbobTeleport user bob can log in to member Nodes only as OS user bob.
kimIf no OS login is specified, it defaults to the same name as the Teleport user, kim.

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 second-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

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:

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 GitHub. For more information, see GitHub SSO.