Skip to main content
Version: 14.x

Getting Started with Access Lists

This guide will help you:

  • Create an access list
  • Assign a member to it
  • Verify permissions granted through the list membership

Prerequisites​

  • A running Teleport Enterprise cluster. For details on how to set this up, see the Enterprise Getting Started guide.

  • The Enterprise tctl admin tool and tsh client tool version >= 14.3.33. You can download these tools by visiting your Teleport account. You can verify the tools you have installed by running the following commands:

    $ tctl version
    # Teleport Enterprise v14.3.33 go1.21

    $ tsh version
    # Teleport v14.3.33 go1.21
  • 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. tctl is supported on macOS and Linux machines. For example: 
    $ tsh login --proxy=teleport.example.com [email protected]
    $ tctl status
    # Cluster  teleport.example.com
    # Version  14.3.33
    # 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 running Teleport cluster.
  • A user with the preset editor role, which will have permissions to create Access Lists.

Step 1/4. Setting up an application service on the cluster for testing​

One of the easiest ways to get resources on the cluster for testing is to set up a Teleport Application Service instance with the debugging application enabled. To do this, add the following config to your teleport.yaml configuration:

app_service:
  enabled: yes
  debug_app: true

And restart Teleport. The "dumper" app should show up in the resource list.

Debug app

Step 2/4. Create a test user​

We need to create a simple test user that has only the requester role, which has no default access to anything within a cluster. This user will only be used for the purposes of this guide, so you may use another user if you so choose. If you would rather use your own user, skip to the next step.

Navigate to the management pane and select "Users." Click on "Create New User" and fill in test-user as the name and select requester as the role.

Create Test User

Click "Save," and then navigate to the provided URL in order to set up the credentials for your test user. Try logging into the cluster with the test user to verify that no resources show up in the resources page.

Step 3/4. Create an Access List​

Next, we'll create a simple access list that will grant the access role to its members. Login as the administrative user mentioned in the prerequisites. Navigate to the management pane and click on access lists. Click on "Create an Access List."

Navigate to create new Access List

Here, fill in a title, description, and grant the access role. Select a date in the future for the next review date.

Fill out Access List Fields

Under "List Owners" select editor as a required role, then add your administrative user under "Add Eligible List Owners." By selecting editor as a required role, this will ensure that any owner of the list must have the editor role in order to actually manage the list. If the user loses this role later, they will not be able to manage the list, though they will still be reflected as an owner.

Select an owner

Under "Members" select requester as a required role, then add your test user to the access list. Similar to the owner requirements, this will ensure that any member of the list must have the requester role in order to be granted the access described in this list. If the user loses this role later, they will no be granted the roles or traits described in the access list.

Add a member

Finally, click "Create Access List" at the bottom of the page.

Step 4/4. Login as the test user​

Again, login as the test user. When logging in now, you should now see the dumper application contained within the cluster, and should be able to interact with it as expected.

Next Steps​

  • Familiarize yourself with the CLI tooling available for managing access lists in the reference.