# Local Users 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: - [Add local users](https://goteleport.com/docs/zero-trust-access/rbac-get-started/users.md#adding-local-users) - [Edit existing users](https://goteleport.com/docs/zero-trust-access/rbac-get-started/users.md#editing-users) - [Delete users](https://goteleport.com/docs/zero-trust-access/rbac-get-started/users.md#deleting-users) --- TIP This guide shows you how to manage human users. For AI agents and machines, see [Machine & Workload Identity - Introduction](https://goteleport.com/docs/machine-workload-identity/introduction.md). --- ## Prerequisites - A running Teleport cluster. If you want to get started with Teleport, [sign up](https://goteleport.com/signup) for a free trial or [set up a demo environment](https://goteleport.com/docs/get-started/deploy-community.md). - 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: **Mac** 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. --- **Windows - Powershell** ``` $ curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zip Unzip the archive and move the `tctl` and `tsh` clients to your %PATH% NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP. Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\) instead. ``` **Linux** All of the Teleport binaries in Linux installations include the `tctl` and `tsh` clients. For more options (including RPM/DEB packages and downloads for i386/ARM/ARM64) see our [installation page](https://goteleport.com/docs/installation.md). ``` $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz $ cd teleport $ sudo ./install Teleport binaries have been copied to /usr/local/bin ``` * 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\@example.com to your Teleport username: ``` $ tsh login --proxy=teleport.example.com --user=email@example.com $ tctl status Cluster teleport.example.com Version 19.0.0-dev 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 User | SSH Logins | Description | | ------------- | ------------- | ---------------------------------------------------------------------- | | `joe` | `joe`, `root` | Teleport user `joe` can log in as user `joe` or `root` on SSH servers. | | `bob` | `bob` | Teleport user `bob` can log in as user `bob` on SSH servers. | | `kim` | | Teleport 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`](https://goteleport.com/docs/reference/cli/tctl.md#tctl-users-add). Let's add a new user to Teleport using the `tctl` tool: **Teleport Community Edition** ``` $ tctl users add joe --logins=joe,root --roles=access,editor ``` **Commercial** ``` $ 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://:443/web/invite/ NOTE: Make sure :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 **Teleport Enterprise/Enterprise Cloud** In addition to users, you can use `tctl` to manage roles and other dynamic resources. See our [Teleport Resources Reference](https://goteleport.com/docs/reference/infrastructure-as-code/teleport-resources.md). For all available `tctl` commands and flags, see our [CLI Reference](https://goteleport.com/docs/reference/cli/tctl.md). You can also configure Teleport so that users can log in using an SSO provider. For more information, see: - [Single Sign-On](https://goteleport.com/docs/zero-trust-access/sso.md) **Teleport Community Edition** In addition to users, you can use `tctl` to manage roles and other dynamic resources. See our [Teleport Resources Reference](https://goteleport.com/docs/reference/infrastructure-as-code/teleport-resources.md). For all available `tctl` commands and flags, see our [CLI Reference](https://goteleport.com/docs/reference/cli/tctl.md). You can also configure Teleport so that users can log in using GitHub. For more information, see [GitHub SSO](https://goteleport.com/docs/zero-trust-access/sso/integrate-idp/github-sso.md).