- Version 15.x
- Version 14.x
- Version 13.x
- Version 12.x
- Older Versions
- Available for:
In Teleport, local users are users managed directly via Teleport, rather than a third-party identity provider.
This guide shows you how to:
To check version information, run the
tctl version and
tsh version commands.
Teleport Enterprise v13.3.9 git:api/14.0.0-gd1e081e go1.21tsh version
Teleport v13.3.9 go1.21Proxy 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
tctlcommands on your administrative workstation using your current credentials. For example:If you can connect to the cluster and run thetsh login --proxy=teleport.example.com --user=[email protected]tctl status
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
tctl statuscommand, you can use your current credentials to run subsequent
tctlcommands from your workstation. If you host your own Teleport cluster, you can also run
tctlcommands on the computer that hosts the Teleport Auth Service for full permissions.
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 User||Allowed OS Logins||Description|
|Teleport user |
|Teleport user |
|If no OS login is specified, it defaults to the same name as the Teleport user, |
Let's add a new user to Teleport using the
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 users ls
User Allowed Logins
Admins can edit user entries via
For example, to see the full list of user records, an administrator can execute:
tctl get users
To edit the user
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
Admins can delete a local user via
tctl users rm joe
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: