Skip to main content
Version: 19.x (unreleased)

Getting Started With Teleport Access Controls

Report an issue with this page

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 for a free trial or set up a demo environment.

  • 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:

      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.

  • 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 protected] to your Teleport username: 
    tsh login --proxy=teleport.example.com --user=[email protected]
    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.
  • 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. If you want to register servers in Teleport without using Docker, see the getting started guide for server access.

Step 1/2. 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.

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

  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.

  4. Assign the absolute path to the configuration file you created to dev-config-path.

  5. Start the Teleport SSH Service on a local Docker container with the configuration and join it to your cluster:

    docker run -v dev-config-path:/etc/teleport/teleport.yaml public.ecr.aws/gravitational/teleport-ent-distroless-debug:13.3.7

  6. 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

  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 the Teleport SSH Service on a local Docker container with the configuration and join it to your cluster:

    docker run -v prod-config-path:/etc/teleport/teleport.yaml public.ecr.aws/gravitational/teleport-ent-distroless-debug:13.3.7

  7. 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-dev

    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-access 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-access role:

    tctl users add alice --roles=local-dev-access

  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 then ame 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:\

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:

Reference guide​

For a full description of the fields you can configure in a Teleport role, see the Teleport Access Controls Reference.