Fork me on GitHub

Local users


This guide covers inviting and managing local user accounts.


Verify that your Teleport client is connected:

$ tctl status

# Cluster
# Version  8.0.7
# CA pin   sha256:sha-hash-here

To try this flow in the cloud, login into your cluster using tsh, then use tctl remotely:

$ tsh login
$ tctl status

Adding and deleting users

Teleport's local user accounts are created and stored in Teleport's internal storage.

Local user accounts can be used alongside external user accounts managed using Github for the open source edition and OIDC and SAML 2.0 for the enterprise.

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 into member nodes as OS user 'joe' or 'root'
bobbobTeleport user 'bob' can log in into member nodes only as OS user 'bob'
rossIf no OS login is specified, it defaults to the same name as the Teleport user - 'ross'.

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 1 hour) and prints the token URL which must be used before the TTL expires.

Signup token has been created. Share this URL with the user:


NOTE: make sure the <proxy> host is accessible.

The user completes registration by visiting this URL in their web browser, picking a password, and configuring the 2nd-factor authentication. If the credentials are correct, the 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 her 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

ross ross

joe joe,root

Joe would then use the tsh client tool to log in to member node "luna" via bastion "work" as root:

tsh --proxy=work --user=joe [email protected]

To delete this user:

tctl users rm joe

Editing users

Admins can edit user entries with the resource commands 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
Have a suggestion or can’t find something?