
In Teleport, local users are users managed directly via Teleport, rather than a third-party identity provider.
Local user accounts can be used alongside external user accounts managed via GitHub.
This guide shows you how to:
Prerequisites
-
A running Teleport cluster. For details on how to set this up, see one of our Getting Started guides.
-
The
tctl
admin tool andtsh
client tool version >= 13.0.3.tctl versionTeleport v13.0.3 go1.20
tsh versionTeleport v13.0.3 go1.20
See Installation for details.
-
A running Teleport Enterprise cluster. For details on how to set this up, see our Enterprise Getting Started guide.
-
The Enterprise
tctl
admin tool andtsh
client tool version >= 13.0.3, which you can download by visiting your Teleport account.tctl versionTeleport Enterprise v13.0.3 go1.20
tsh versionTeleport v13.0.3 go1.20
Please use the latest version of Teleport Enterprise documentation.
- Make sure you can connect to Teleport. Log in to your cluster using
tsh
, then usetctl
remotely:tsh login --proxy=teleport.example.com [email protected]tctl statusCluster teleport.example.com
Version 13.0.3
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
You can run subsequent
tctl
commands in this guide on your local machine.For full privileges, you can also run
tctl
commands on your Auth Service host.
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 User | Allowed OS Logins | Description |
---|---|---|
joe | joe , root | Teleport user joe can log in to member Nodes as user joe or root on the OS. |
bob | bob | Teleport user bob can log in to member Nodes only as OS user bob . |
kim | If 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
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 lsUser 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.