# Getting Started With Teleport Access Controls Teleport Role-Based Access Control (RBAC) is a system for managing who can access what within your infrastructure. Instead of assigning permissions directly to users, you create roles that define sets of permissions, then assign those roles to users. This guide helps you understand RBAC in Teleport by walking you through the process of applying labels to resources, setting up minimal roles, and accessing resources available to a particular role. ## How it works This guide illustrates how to register a server with Teleport using a Docker container and the Teleport SSH Service in order to apply RBAC rules for accessing the server. While the example uses a Teleport-protected server, applying RBAC rules for accessing infrastructure resources works in similar ways for any Teleport-protected resource. ## 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 18.7.3 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. * A Teleport user with permissions to create join tokens and other roles. We recommend using a demo cluster with the preset `editor` role. * Docker installed on your workstation. Docker is only required for the local demo environment used in this guide. You can find installation instructions for Docker on [Docker's website](https://docs.docker.com/get-docker/). If you want to register servers in Teleport without using Docker, see the getting started guide for [server access](https://goteleport.com/docs/enroll-resources/server-access/getting-started.md). ## Step 1/3. Enroll resources with labels In this section, you will enroll two servers with your Teleport cluster. One server will have the `env:local-dev` label and the other will have the `env:local-prod`. Later in this guide, you will create a role that will allow a user to access a server with the `env:local-dev` label and deny access to the `env:local-prod` label. Before following these instructions, assign teleport.example.com:443 to your Teleport cluster hostname and port, but not the scheme (https\://). ### Enroll a server with the `env:local-dev` label 1. Create a join token for the server to use to join the cluster: ``` $ tctl tokens add --type=node --format=text ``` 2. Assign the token to token and the host and web port of your Teleport Proxy Service to example.teleport.sh:443. 3. Copy the following Teleport configuration to a file called `local-dev.yaml`: ``` version: v3 teleport: data_dir: /var/lib/teleport join_params: token_name: token method: token proxy_server: example.teleport.sh:443 auth_service: enabled: "false" ssh_service: enabled: "true" labels: env: local-dev proxy_service: enabled: "false" ``` This Teleport configuration enables the Teleport SSH Service, which enrolls a server in your Teleport cluster. The `ssh_service.labels` field adds a label to the server called `env:local-dev`. 4. Assign the absolute path to the configuration file you created to dev-config-path. 5. Start a Docker container on your workstation to prepare a server that you want to enroll as a resource in your Teleport cluster: ``` $ docker run -v dev-config-path:/etc/teleport.yaml --interactive --tty ubuntu:24.04 /bin/bash ``` 6. In your container shell, install curl and sudo: ``` $ apt-get update && apt-get install -y curl sudo ``` 7. In your container shell, install Teleport on your container: ``` $ curl "https://teleport.example.com:443/scripts/install.sh" | bash ``` 8. In your container shell, start the Teleport SSH Service: ``` $ teleport start ``` Keep the terminal attached to the container shell open. 9. Wait for a minute or so. Verify that you have logged in via `tsh login` and check that the server has joined your cluster by listing enrolled servers by label. You should see the server you just enrolled: ``` $ tsh ls env=local-dev Node Name Address Labels ------------ ---------- ------------- 80f60427d316 ⟵ Tunnel env=local-dev ``` ### Enroll a server with the `env:local-prod` label 1. Open a separate terminal. 2. Create a join token for the server to use to join the cluster: ``` $ tctl tokens add --type=node --format=text ``` 3. Assign the token to token. 4. Copy the following YAML document to a file called `local-prod.yaml`. This configuration starts the Teleport SSH Service with the label `env:local-prod`: ``` version: v3 teleport: data_dir: /var/lib/teleport join_params: token_name: token method: token proxy_server: example.teleport.sh:443 auth_service: enabled: "false" ssh_service: enabled: "true" labels: env: local-prod proxy_service: enabled: "false" ``` 5. Assign the absolute path to the configuration file you created to prod-config-path. 6. Start a Docker container on your workstation to prepare a server that you want enroll as a resource in your Teleport cluster: ``` $ docker run -v prod-config-path:/etc/teleport.yaml --interactive --tty ubuntu:24.04 /bin/bash ``` 7. In your container shell, install curl and sudo: ``` $ apt-get update && apt-get install -y curl sudo ``` 8. In your container shell, install Teleport on your container: ``` $ curl "https://teleport.example.com:443/scripts/install.sh" | bash ``` 9. In your container shell, start the Teleport SSH Service: ``` $ teleport start ``` Keep the terminal attached to the container shell open. 10. Ensure that the server has joined the cluster: ``` $ tsh ls env=local-prod Node Name Address Labels ------------ ---------- -------------- ba2290caf694 ⟵ Tunnel env=local-prod ``` ## Step 2/3. Create a Teleport role Create a role that can access servers with the `env:local-dev` label but not the `env:local-prod` label. 1. Create a file called `role.yaml` with the following content: ``` kind: role version: v7 metadata: name: local-dev-only spec: allow: logins: [root] node_labels: env: local-* deny: node_labels: env: local-prod ``` The `allow` block indicates what the user is allowed to access. By default, nothing is allowed, so each role must include at least one `allow` field to provide permissions. The `spec.allow.logins` field allows the user to assume the `root` login when connecting to a server. You can change this to a less permissive login, but we are using `root` because it is the only available login on the Docker containers we spun up. `spec.allow.node_labels` uses wildcard syntax, which matches one or more characters, to allow users to connect to any server with a label that begins `env:local-`, such as the `env:local-dev` and `env:local-prod` labels we assigned to our servers. However, since the `deny.node_labels` field specifies `env:local-prod`, a user with this role would only be able to access the server with the `env:local-dev` label. 2. Create the role: ``` $ tctl create role.yaml ``` ## Step 3/3. Access your server In this step, you will create a local Teleport user with the `local-dev-only` role, then list available servers and connect the one with the label `env:local-dev`. 1. Create a local user named `alice` with the `local-dev-only` role: ``` $ tctl users add alice --roles=local-dev-only ``` 2. Follow the instructions in your terminal to sign in as `alice`. 3. In your terminal, log out of your cluster and log in again, assigning example.teleport.sh to the domain name of your Teleport Proxy Service: ``` $ tsh logout $ tsh login --user=alice --proxy=example.teleport.sh ``` 4. List all servers available for your user to access. You should only see one: ``` $ tsh ls Node Name Address Labels ------------ ---------- ------------- ba2290caf694 ⟵ Tunnel env=local-dev ``` Since `alice` is denied access to servers with the `env:local-prod` label, only the server with the `env:local-dev` label is available to connect to. 5. Access the server using the value of the `Node Name` field as shown in `tsh ls`. Assign ba2290caf694 to the name of your server: ``` $ tsh ssh root@ba2290caf694 ``` ## Next steps In this guide, you created a Teleport role that allowed and denied access to SSH servers based on the labels that the servers were enrolled with. Read about more things you can do with Teleport roles. ### Learn more Teleport RBAC fundamentals Read more about using Teleport roles to govern RBAC: - [Add Labels to Resources](https://goteleport.com/docs/zero-trust-access/rbac-get-started/labels.md) - [Role Templates](https://goteleport.com/docs/zero-trust-access/rbac-get-started/role-templates.md) ### Configure RBAC for specific kinds of resources You can label all Teleport-protected resources and use those labels to set RBAC policies. In addition, each kind of Teleport resource also has more specific attributes that you can use to control access. Read the guides below to refine your RBAC for each kind of resource: - [Servers](https://goteleport.com/docs/enroll-resources/server-access/rbac.md) - [Databases](https://goteleport.com/docs/enroll-resources/database-access/rbac.md) - [Kubernetes clusters](https://goteleport.com/docs/enroll-resources/kubernetes-access/controls.md) - [Remote desktops](https://goteleport.com/docs/enroll-resources/desktop-access/rbac.md) - [Web applications](https://goteleport.com/docs/enroll-resources/application-access/configuration/controls.md) ### Reference guide For a full description of the fields you can configure in a Teleport role, see the [Teleport Access Controls Reference](https://goteleport.com/docs/reference/access-controls/roles.md).