Getting Started with Access Lists

Report an IssueView as Markdown

Is this page helpful?

How can we improve this page?

Identity Governance is available only with Teleport Enterprise.

This guide walks you through the Teleport Web UI to:

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

If you'd rather manage Access Lists as code, follow the Access Lists with Terraform and Kubernetes Operator guide instead.

Prerequisites

• A running Teleport Enterprise (v18.8.0 or higher) cluster. If you don't have one yet, sign up for a free trial.

• Permissions to create Access Lists, users, and roles. These are included in the preset editor role, or you can copy and paste the following into your own role:

  allow:
    rules:
    - resources:
      - access_list
      - user
      - role
      verbs:
      - read
      - list
      - create
      - update
      - delete
  

Step 1/4. Enroll a test resource

We need at least one resource on the cluster to grant access to. If you already have a resource enrolled that you can use for testing, skip to the next step.

Otherwise, follow the Connect Infrastructure guide to enroll a host through the Web UI's guided setup. The linked page uses an Ubuntu server as its example, but the same flow works for your own machine (Linux or macOS) — just pick your OS during the guided setup and run the install command it gives you.

tip

When the guided setup asks you to add labels, add at least one — for example, env: test. We'll use this label in Step 3 to select the host. (You can also match all hosts with a * wildcard, but using a real label is closer to how you'd build an Access List in practice.)

The rest of this guide assumes you've enrolled an SSH server.

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.

From the sidebar menu, click Zero Trust Access > Users > Enroll Users. Fill in test-user as the name and select requester as the role.

Submit the form to create the user, 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 an Access List that grants its members access to the SSH host we enrolled in Step 1. Login as the admin user mentioned in the prerequisites.

From the sidebar menu, hover over Add New then click Access List.

Enter test-list as the Access List name, optionally add a description, then select Standing Access Guide — this is the flow that grants members access on login, which is what we want for this tutorial. (Other options: Just-in-Time Access makes resources requestable instead of granted automatically, and the Custom Form lets you assign existing roles directly without the guided flow.)

Click Start Guide.

Prefer Terraform?

As you fill out the guided flow, a Terraform panel on the side mirrors your input live. At the final Deployment step you can choose to apply the list with Teleport directly or follow the in-UI instructions to apply it with Terraform.

1. Define Access to Resources

• Click Server from the resource-type column on the left.
• Click the env: test label next to your host (or whichever label you set in Step 1) to select it.
• If you didn't add a label, type * into the label input box and press Enter to match all servers.

This gives members of the list access to SSH servers matching the env: test label (or any SSH server, if you used *).

Previewing Resources

After defining access for a resource type, the UI shows a preview of matching resources. The preview is limited by your own role permissions — members may be granted access to additional resources that aren't visible to you.

2. Define Resource Identities or Principals

• Under Server Identities Logins, add the OS user(s) you want members to be able to log in as on the host (for example, ubuntu on a Linux server or your local username on macOS).

Note: this screen only asks for SSH logins because Server was the only resource type you selected in the previous step.

3. Basic Information

• Confirm the title and description.
• Select a date in the future for the next review.

4. Define Membership

• Add your test user as a member.
• Optionally, expand Optional Advanced Settings and select requester as a required role. The required role ensures any member of the list must hold requester to be granted access; if a member loses the role later, they will not be granted the access described in the list.

5. Define Ownership

• Add your admin user as an eligible owner.
• Optionally, expand Optional Advanced Settings and select editor as a required role. The required role ensures any owner must hold editor to manage the list; if an owner loses the role later, they remain reflected as an owner but cannot manage the list.

6. Deployment

• Review the summary and click Create Access List Now.

Editing the generated roles

Avoid directly modifying the roles the guided flow creates for this Access List. Keep their names and their teleport.internal/access-list-preset* labels unchanged — the Web UI relies on both to recognize them as the roles generated for this Access List. To change what the list grants, update it through the Web UI Access List editor:

1. From the sidebar menu, click Identity Governance > Access Lists.
2. Click on the target Access List.
3. Click the Access Definition tab.
4. Click Edit Access.

If you created the list with Terraform produced by the Web UI editor, you can still use the web editor to update the Access List and copy the updated Terraform it generates.

Editing the roles directly (via Terraform, tctl, or the role editor) may make the Access List editor in the Web UI unable to parse them (only a limited subset of role fields is supported by the editor) — at which point you can no longer use the Web UI editor to change the list's grants, and must update the roles directly for the rest of the Access List's life.

Step 4/4. Log in as the test user

Log in as the test user in the Web UI. You should see the SSH server from Step 1 in the Resources list. Click Connect, then click one of the logins you allowed in the Define Resource Identities or Principals step to SSH into the server.

Cleanup (optional)

If you'd like to remove the SSH server you enrolled in Step 1, follow Uninstall Teleport.

Once the agent is stopped, Teleport automatically removes the server from the resource list after a few minutes.

Next steps

• Read more about the flow you just used in Standing Access Lists.
• Create an Access List whose members can request temporary access to resources instead of receiving them on login.
• Create an Access List by assigning existing roles directly with the Custom Form.
• Read Creating Access Lists with IaC for instructions on managing Access Lists with the Teleport Terraform provider and Kubernetes operator.
• Familiarize yourself with the CLI tooling available for managing Access Lists in the reference.
• Learn how to work with nested Access Lists in the nested Access Lists guide.